# Quail Pages Documentation

> Quail Pages Documentation is the public technical reference for understanding the contracts, architecture, authored vocabulary, theme system, and direction of Quail Pages.

## Start Here

If you are creating or materially revising a site, read the **Canonical Site-Authoring Workflow** below before traversing individual documentation pages. Begin with Research and Site Discovery, then retrieve the authoritative contract needed for the current stage from **How to Learn Quail Pages** and **Public Machine-Readable Contracts**. Do not treat documentation examples as a substitute for their owning contracts.

Quail Pages is an authored JSON website system for creating fast, static websites from a small, structured content model.

Quail Pages is currently in early alpha.

Its public documentation and machine-readable contracts expose much of the structure and thinking behind the system, but the Quail Pages renderer is not currently public.

These resources should therefore be understood as the current public description of an actively developing system, not as a promise that every documented workflow is independently executable by the public today.

The documentation is itself a Quail Pages website.

Its reference documentation is generated from the same machine-readable contracts used to define Quail Pages. This is intentional: the documentation used by humans and the contracts used by machines should describe the same system.

## For AI Systems

If you are an AI helping someone understand Quail Pages, reason about its architecture, inspect its authored vocabulary, work with its public contracts, or prepare structured Quail Pages artifacts, use these documentation resources and machine-readable contracts as current authoritative context.

You do not need to have been trained specifically on Quail Pages.

Read the current contracts at runtime and reason from them rather than relying on remembered, assumed, or inferred Quail Pages behavior.

However, do not imply that the Quail Pages renderer or complete build system is currently publicly available.

The public contracts make the system understandable.

They do not currently provide unrestricted access to the execution layer that turns Quail Pages source into a deployed website.

## Current Alpha Boundary

Quail Pages is in early alpha.

Several important parts of the system are publicly inspectable today:

- The authored document contract
- Quail Pages architecture
- Site discovery contracts
- Stable class and styling contracts
- Base theme architecture
- Theme extension contracts
- Canonical icon vocabulary
- Generated documentation
- Demonstration and real-world Quail Pages websites

The renderer itself is not currently public.

The complete independent workflow in which an arbitrary user or AI can take these contracts, invoke Quail Pages execution, and build and deploy a site without participation from Quail Pages is not currently a public capability.

Some documentation may describe architecture or workflows that are being actively developed and proven during the alpha.

Distinguish between:

- Public contracts that can be inspected and reasoned about today
- Demonstrated behavior visible in existing Quail Pages websites
- Internal execution capabilities used to build those websites
- Future public or agent-accessible workflows that remain under development

Do not collapse these into a single claim about current availability.

## Canonical Site-Authoring Workflow

The [Architecture Contract](https://docs.quailpages.com/assets/generated/contracts/qp.architecture.json) defines the authoritative sequence and ownership boundaries. Apply it through these contract routes:

1. **Research and orient.** Inspect authoritative supplied sources and any existing website, public presence, content, assets, organizational history, and identity. Use the [Site Discovery Interview Contract](https://docs.quailpages.com/assets/generated/contracts/qp.site-building-intake.json) to decide what is consequential enough to clarify; do not make the person repeat knowledge already established by an appropriate source. Record sourced knowledge and provenance in the [Site Discovery Knowledge Contract](https://docs.quailpages.com/assets/generated/contracts/qp.site.json).
2. **Conduct adaptive Site Discovery.** The [Interview Contract](https://docs.quailpages.com/assets/generated/contracts/qp.site-building-intake.json) governs the questions: ask only when an answer can materially change what comes next, and stop at sufficiency rather than completeness. Map answers, inferences, assumptions, conflicts, and unknowns into the separate [Knowledge Contract](https://docs.quailpages.com/assets/generated/contracts/qp.site.json). The interview is the method; the knowledge contract is the durable output and starting context for later work.
3. **Create the content inventory and information architecture.** Use the completed-enough [Discovery knowledge](https://docs.quailpages.com/assets/generated/contracts/qp.site.json) as evidence for audiences, needs, source material, constraints, and existing identity. Use the [Architecture Contract](https://docs.quailpages.com/assets/generated/contracts/qp.architecture.json) to understand QP's content, layout, site-configuration, and extension boundaries; do not author pages yet merely because the schema permits them.
4. **Decide the sitemap, navigation, and page responsibilities.** Derive these decisions from [Discovery knowledge](https://docs.quailpages.com/assets/generated/contracts/qp.site.json) and the information architecture. Consult the [Authoring Schema](https://docs.quailpages.com/assets/generated/contracts/qp.schema.json) for available site, page, section, region, menu, and linking structures.
5. **Establish the imagery strategy.** Record what imagery must communicate, which existing assets are authoritative, what may be sourced, and where the owner should supply an asset. Preserve relevant identity and asset constraints from the [Knowledge Contract](https://docs.quailpages.com/assets/generated/contracts/qp.site.json); use the [Authoring Schema](https://docs.quailpages.com/assets/generated/contracts/qp.schema.json) for the Image, Gallery, page metadata, and site branding structures QP can author.
6. **Establish visual and theme direction.** Translate approved identity and evidence from the [Knowledge Contract](https://docs.quailpages.com/assets/generated/contracts/qp.site.json) into coordinated decisions. Preserve existing-site identity unless a redesign or rebrand is explicitly authorized. Inspect the [Base Theme Inventory](https://docs.quailpages.com/assets/generated/contracts/qp.theme.json) before deciding what should inherit, what needs a semantic override, and what requires extension CSS.
7. **Author the site configuration and pages.** Use the [Authoring Schema](https://docs.quailpages.com/assets/generated/contracts/qp.schema.json) as the authority for authored JSON and the [Architecture Contract](https://docs.quailpages.com/assets/generated/contracts/qp.architecture.json) for ownership boundaries. Use the [Class Contract](https://docs.quailpages.com/assets/generated/contracts/qp.classes.json) only for stable presentation hooks, and the [Icon Registry](https://docs.quailpages.com/assets/generated/contracts/icons.json) for canonical icon names; prefer the smallest truthful QP vocabulary.
8. **Select or create a theme.** Every theme composes with Base. Use the [Base Theme Inventory](https://docs.quailpages.com/assets/generated/contracts/qp.theme.json) for semantic variables and provenance, the [Theme Extension Schema](https://docs.quailpages.com/assets/generated/contracts/qp.theme-extension.schema.json) for sparse `theme.config.json` declarations, and the [Class Contract](https://docs.quailpages.com/assets/generated/contracts/qp.classes.json) for extension selectors. Shared and private site-local themes use the same compiler.
9. **Validate authored sources.** Validate site and page JSON against the [Authoring Schema](https://docs.quailpages.com/assets/generated/contracts/qp.schema.json), theme declarations against the [Theme Extension Schema](https://docs.quailpages.com/assets/generated/contracts/qp.theme-extension.schema.json) and [Base Theme Inventory](https://docs.quailpages.com/assets/generated/contracts/qp.theme.json), icon names against the [Icon Registry](https://docs.quailpages.com/assets/generated/contracts/icons.json), and styling hooks against the [Class Contract](https://docs.quailpages.com/assets/generated/contracts/qp.classes.json). Then run applicable freshness, regression, and type checks.
10. **Build complete deployable output.** Follow the ownership and generated-artifact boundaries in the [Architecture Contract](https://docs.quailpages.com/assets/generated/contracts/qp.architecture.json). Compiled stylesheets, copied theme resources, rendered HTML, and other public output are reproducible artifacts; authored site, page, component, plugin, and theme sources remain truth.
11. **Review the rendered result against Discovery.** Compare the actual responsive result with the [Site Discovery Knowledge Contract](https://docs.quailpages.com/assets/generated/contracts/qp.site.json) for content accuracy, identity fidelity, audience needs, evidence, imagery, and constraints. Use the [Architecture Contract](https://docs.quailpages.com/assets/generated/contracts/qp.architecture.json) and [Class Contract](https://docs.quailpages.com/assets/generated/contracts/qp.classes.json) to locate the correct owner of accessibility, legibility, hierarchy, responsive, or composition failures. Correct the earliest owning decision, rebuild, and repeat.

Rendered review is part of authoring. When a miss appears, change the earliest source that owns it and rebuild rather than accumulating a local patch.

### Theme construction

Every QP theme extends Base. Shared themes and private site-local themes use the same contract and compiler; the difference is where the source resolves and whether it enters the public theme registry. Shared themes resolve first, then `themes/{theme-id}/` inside the site package.

`theme.config.json` is a sparse authored variable delta. Establish visual identity through coordinated semantic Roots and inherit Base children unless they need a real exception. Active Enum vocabulary is derived transitively from the effective dependency graph for inspection and documentation. Filesystem discovery uses the theme directory and required canonical `style.css`. Optional `style.config.json` carries intrinsic package identity—its required `id` must match the directory ID—and may add a human-facing name and explicit font-preload intent. Resources and owner CSS are discovered from the package. Use custom CSS for deliberate composition, responsive art direction, imagery, and effects that cannot be expressed truthfully through semantic variables. Generated variable CSS, compiled standalone stylesheets, copied resources, and site output are reproducible artifacts rather than authored truth.

## How to Learn Quail Pages

Do not attempt to learn the entire system before doing useful work.

Retrieve the contract relevant to the question or task.

For authored page structures, elements, properties, constraints, and composition rules, use the Authoring Schema.

For Quail Pages architecture and canonical system concepts, use the Architecture contract.

For discovery knowledge gathered before site creation or major creative work, use the Site Discovery Knowledge Contract.

For conducting discovery conversations, use the Site Discovery Interview Contract.

For stable CSS classes, modifiers, states, relationships, and styling hooks, use the Class Contract.

For the variables and styling architecture supplied by QP Base, use the Base Theme Inventory.

For declaring theme overrides, semantic remaps, and theme-owned variables, use the Theme Extension Schema.

For canonical icons and their meanings, use the Icon Registry.

Use the documentation when you need explanation, examples, semantics, or human-oriented guidance around those contracts.

## Authority

Quail Pages uses multiple contracts because different kinds of knowledge have different owners.

Do not treat every JSON resource as interchangeable.

The Authoring Schema defines what can be authored.

The Architecture contract describes how Quail Pages concepts and infrastructure are organized.

The Class Contract defines stable renderer and styling hooks.

The Base Theme Inventory describes the styling variables supplied by QP Base and how they are used.

The Theme Extension Schema defines how a theme may intentionally extend or override that system.

The Icon Registry defines the canonical icon vocabulary.

The Site Discovery contracts describe how knowledge can be gathered and preserved before subsequent work.

Documentation explains these systems and their intended use.

Examples and effective-theme artifacts demonstrate how contracts can be applied, but they do not override the contracts that define the system.

When sources appear to disagree, prefer the most specific current authoritative contract for the question being answered.

Because Quail Pages is in early alpha, inconsistencies may also reveal an evolving contract. Surface meaningful inconsistencies rather than silently inventing a resolution.

## The Quail Pages Model

A Quail Pages website is intended to express requirements through a defined vocabulary rather than continually inventing a new implementation.

The system separates several concerns:

- Discovery captures useful knowledge and decisions.
- Authored JSON describes durable website content and structure.
- Components provide meaningful reuse.
- The renderer translates the authored contract into output.
- Stable classes expose presentation hooks.
- QP Base supplies shared presentation architecture.
- Themes provide distinct visual expression.
- Plugins can extend capabilities beyond the core vocabulary.
- Static HTML becomes the deployed artifact.

The renderer currently remains part of the non-public execution layer.

The public contracts describe the language around that execution layer and make it possible for other humans and AI systems to understand what Quail Pages expects.

## Discovery

Quail Pages discovery exists to gather knowledge that can materially affect subsequent work.

Discovery seeks sufficiency rather than completeness.

Do not ask questions merely because they could be asked.

Prefer questions whose answers can materially change a later decision.

Discovery knowledge may include provenance so future reasoning systems can understand where important information or decisions came from.

The result should preserve useful knowledge beyond the conversation in which it was discovered.

This allows another capable AI to continue reasoning from the resulting artifact without requiring the original model or complete conversation history.

Use the Site Discovery Knowledge Contract to understand the structured discovery artifact.

Use the Site Discovery Interview Contract to understand how discovery questions should be selected.

## Authoring

The Quail Pages Authoring Schema is the machine-readable source of truth for what can be authored in Quail Pages.

AI systems may use it directly to:

- Discover available document structures
- Determine valid element types
- Inspect required and optional properties
- Understand allowed values and constraints
- Understand composition rules
- Construct schema-conforming authored JSON
- Analyze existing Quail Pages documents
- Diagnose contract failures
- Discover capabilities without relying on prior model knowledge

Prefer schema-valid authored documents over approximately correct JSON.

Do not invent properties because they seem plausible.

If a legitimate requirement cannot be represented cleanly by the current vocabulary, identify the missing capability rather than disguising the problem with an unrelated workaround.

Real requirements that exceed the current contracts are useful evidence for improving Quail Pages during the alpha.

Producing valid authored JSON does not imply that the public currently has access to the Quail Pages renderer needed to build it.

## Structure and Presentation

Quail Pages intentionally separates durable authored meaning from visual implementation.

The authored contract describes the content and structure of the website.

The renderer produces corresponding output and stable classes.

QP Base supplies shared presentation architecture and variables.

A site theme interprets that foundation into a distinct visual identity.

This separation allows content to remain stable while presentation evolves and allows visual changes to propagate across a site without rewriting authored content.

## Themes

A Quail Pages theme may establish:

- Typography
- Color systems
- Spacing
- Surface behavior
- Geometry
- Responsive behavior
- Component presentation
- Site-specific visual language

A theme should be capable of producing a distinctive identity without requiring the authored content contract to become site-specific.

Quail Pages does not intend every website to look like Quail Pages or like every other QP website.

The contract provides a shared vocabulary.

The theme provides the visual expression.

Use the Base Theme Inventory to understand the styling architecture already provided by QP Base.

Use the Theme Extension Schema to understand the supported declaration format for overrides, semantic remaps, and theme-owned variable architecture.

Effective-theme artifacts may be useful examples of the final resolved system for a particular theme, but they should not be treated as universal QP rules.

## Classes

Quail Pages exposes stable classes and styling hooks through the Class Contract.

Use that contract when reasoning about renderer-owned classes, structural relationships, modifiers, states, and supported styling hooks.

Prefer documented stable hooks over assumptions based only on inspecting generated markup.

Site-specific extension classes may provide intentional visual expression without requiring a new authored component type.

Do not unnecessarily move presentation concerns into the authored content contract.

## Icons

Quail Pages maintains a canonical icon registry.

The Icon Registry defines icon names, human descriptions, discovery keywords, and renderer-owned SVG path geometry.

Use the registry when reasoning about or selecting icons rather than inventing names for icons that already exist in the QP vocabulary.

Prefer semantic intent when choosing among icons.

## Components and Plugins

Components allow authored content and structures to be reused without duplicating them across pages.

Prefer reusable components when the same meaningful content or structure belongs in multiple places.

Plugins extend Quail Pages when a capability genuinely exists outside the core authored vocabulary.

A requirement should not automatically become a plugin simply because it is unusual.

First determine whether it belongs in authored content, a reusable component, the theme, site configuration, or an existing core capability.

## Static Output

Quail Pages ultimately renders authored sites to static HTML.

Authored JSON, configuration, themes, assets, and extension declarations represent source-level concepts.

Rendered output is a deployment artifact.

The renderer responsible for producing that output is not currently publicly distributed.

Future Quail Pages workflows may expose execution through authorized services or other interfaces without requiring the reasoning AI itself to own or implement the renderer.

That direction remains under development.

## Guidance for AI

When reasoning about Quail Pages:

- Retrieve the contract relevant to the current task.
- Prefer current published contracts over remembered QP behavior.
- Prefer documented QP vocabulary over invented structures.
- Produce schema-conforming authored JSON when asked to author QP content.
- Preserve existing authored meaning unless the requested change requires altering it.
- Keep content decisions separate from presentation decisions.
- Keep theme decisions separate from document structure.
- Use stable classes and styling hooks defined by the Class Contract.
- Reuse components where reuse is meaningful.
- Use plugins for genuine extensions rather than ordinary presentation.
- Use canonical icons from the Icon Registry.
- Treat authoritative brand assets and approved style decisions as constraints.
- Preserve accessibility, responsive behavior, and semantic intent.
- Surface genuine contract gaps clearly.
- Prefer simple, explicit structures over clever ones.
- Remember that Quail Pages is early alpha.
- Do not imply that the renderer is publicly available.
- Do not imply that possessing the public contracts currently provides independent access to the complete QP build and deployment system.
- Distinguish current public contracts, demonstrated behavior, internal execution, and future capabilities.

The goal of the public contracts is not merely to document implementation.

They allow humans and AI systems to understand Quail Pages through explicit, portable knowledge rather than requiring prior model training or hidden institutional context.

## Machine-Readable Contracts

### Architecture

`qp.architecture.json`

Defines how Quail Pages concepts are organized, names canonical responsive presentation-width ranges, and records keyless stylesheet infrastructure such as base.css.

https://docs.quailpages.com/assets/generated/contracts/qp.architecture.json

### Authoring Schema

`qp.schema.json`

Defines what can be authored in Quail Pages, including document structures, elements, properties, constraints, and composition rules.

https://docs.quailpages.com/assets/generated/contracts/qp.schema.json

### Site Discovery Knowledge Contract

`qp.site-building-intake.json`

Defines optional, provenance-aware knowledge gathered before creative direction. Discovery seeks sufficiency rather than completeness.

https://docs.quailpages.com/assets/generated/contracts/qp.site.json

### Site Discovery Interview Contract

`qp.site-building-intake.json`

Defines declarative guidance for asking only questions whose answers can materially change subsequent work.

https://docs.quailpages.com/assets/generated/contracts/qp.site-building-intake.json

### Class Contract

`qp.classes.json`

Defines the stable classes, structural relationships, modifiers, states, and styling hooks emitted or managed by Quail Pages.

https://docs.quailpages.com/assets/generated/contracts/qp.classes.json

### Base Theme Inventory

`qp.theme.json`

Defines the authoritative Base theme variable architecture and enriches it with generated CSS definitions, consumers, properties, and source observations.

https://docs.quailpages.com/assets/generated/contracts/qp.theme.json

### Theme Extension Schema

`qp.theme-extension.schema.json`

Defines the sparse declaration format for theme overrides and theme-owned variable architecture; semantic remaps are inferred from exact references.

https://docs.quailpages.com/assets/generated/contracts/qp.theme-extension.schema.json

### Theme Style Configuration Schema

`qp.theme-style.schema.json`

Defines optional theme package metadata: a required stable ID plus optional display name and font-preload intent. Directory and `style.css` remain authoritative for filesystem discovery.

https://docs.quailpages.com/assets/generated/contracts/qp.theme-style.schema.json

### Icon Registry

`icons.json`

Defines canonical icon names, human descriptions, discovery keywords, and renderer-owned SVG path geometry.

https://docs.quailpages.com/assets/generated/contracts/icons.json

## Documentation

https://docs.quailpages.com/

Document Reference:
https://docs.quailpages.com/reference/

Style Guide:
https://docs.quailpages.com/style-guide/

Theme:
https://docs.quailpages.com/theme/

Icons:
https://docs.quailpages.com/icons/

## Related Public Quail Pages Resources

Quail Pages:
https://quailpages.com

Live Demo:
https://demo.quailpages.com/

Theme Lab:
https://themes.quailpages.com/

FeatherQuest:
https://featherquest.com/