{ "stylesheetInfrastructure": { "description": "Infrastructure stylesheets sit outside the PascalCase architecture-key and class-contract ownership system.", "files": { "base.css": { "description": "Global document and browser foundations: reset and box sizing, html/body baselines, global typography and link mechanics, responsive media defaults, document background and color, and theme font-face declarations or exceptional document-global styling.", "mustNotOwn": "QP primitive or component class hooks, component-specific styling, or behavior already owned by an architecture primitive.", "themeUse": "A theme MAY own its own base.css for theme-level document foundations that truthfully map to the infrastructure responsibilities of base.css, including font-face declarations, document/body foundation treatment, global typography/link mechanics, responsive media defaults, and exceptional document-global styling. Theme base.css MUST NOT become a catch-all for QP architecture-owner overrides.", "architectureKey": null, "classContractKey": null }, "variables.css": { "description": "Shared and theme-specific semantic CSS custom properties consumed by infrastructure and architecture-owner stylesheets.", "architectureKey": null, "classContractKey": null, "authorship": "Generated artifact. Theme authors MUST NOT edit or independently author variables.css. Author variable decisions in theme.config.json using the Theme Extension Contract; regenerate variables.css through the theme compiler." }, "style.css": { "description": "Theme stylesheet entry point that orders infrastructure and architecture-owner imports.", "architectureKey": null, "classContractKey": null, "authorship": "Required authored assembly entry point for every completed non-Base theme source. A completed theme MUST include style.css. It is not a general-purpose authoring stylesheet.", "extensionExample": [ "@import \"../qp-base/style.css\";", "@import \"./variables.css\";", "@import \"./styles/base.css\";", "@import \"./styles/page-header.css\";", "@import \"./styles/menu.css\";", "@import \"./styles/card-list.css\";" ], "extensionGuidance": "The example is illustrative, not a required file list. Do not create empty owner stylesheets merely to mirror Base. Component-specific theme CSS belongs in the stylesheet associated with that architecture owner; do not accumulate owner styling directly in style.css or a monolithic theme stylesheet.", "requiredThemeAssemblyOrder": [ "Import the complete Base style.css first.", "Import the theme's generated variables.css second.", "Import any theme-owned infrastructure stylesheet such as base.css next, when present.", "Import theme architecture-owner stylesheets after infrastructure, in a stable deterministic order." ], "completionRule": "Theme Creation is incomplete if the theme source does not contain its canonical style.css entry point. style.css MUST assemble the effective theme and MUST NOT contain architecture-owner declarations merely to avoid creating the corresponding owner stylesheet." } }, "referenceImplementation": { "principle": "The contracts define Quail Pages architecture and ownership; Base is the canonical reference implementation of that architecture. Study Base to understand existing mechanics and extension seams, but do not copy its declarations into a theme or infer new framework contracts from incidental implementation details.", "publishedContract": "https://docs.quailpages.com/assets/generated/contracts/qp.architecture.json", "publishedBaseCssRoot": "https://docs.quailpages.com/assets/generated/base-css/", "studyBeforeExtending": "Before authoring or materially revising a theme, inspect Base style.css, variables.css, and the Base architecture-owner stylesheet for each owner the theme intends to change. Determine what Base already provides, which semantic variables control the desired presentation, and which existing class hooks own the relevant structure before introducing extension CSS, theme-owned variables, or additional classes." }, "ownership": { "principle": "Stylesheet ownership follows Quail Pages architectural ownership, not theme identity, brand, feature, project, or implementation convenience.", "rule": "When a theme styles or extends an existing QP architecture owner, authored CSS MUST live in the theme stylesheet associated with that owner. For example, Card styling belongs in card.css, Cta styling in cta.css, SiteHeader styling in site-header.css, and PageHeader styling in page-header.css.", "infrastructure": "Theme infrastructure CSS may live in the matching infrastructure stylesheet when it truthfully owns an infrastructure concern. In particular, a theme may author its own base.css for the document-global responsibilities defined by stylesheetInfrastructure.files.base.css.", "prohibitedAggregation": "Do not aggregate unrelated architecture-owner overrides into a theme-named or catch-all stylesheet such as axomo.css, brand.css, theme.css, overrides.css, primitives.css, components.css, or similar. Do not move owner styling into base.css or style.css merely to reduce file count.", "assembly": "Every completed non-Base theme MUST contain style.css as its canonical authored assembly entry point. It imports the complete Base style.css first, generated theme variables.css second, then any theme-owned infrastructure stylesheets such as base.css, followed by only the architecture-owner stylesheets the theme actually owns. style.css is assembly only; do not place owner-specific declarations in it and do not create empty owner stylesheets merely to mirror Base.", "reason": "Mirroring QP ownership keeps Base and theme extensions discoverable and maintainable: an author changing a QP owner can inspect the Base owner stylesheet and the theme owner stylesheet without searching a monolithic brand override file." } }, "themeExtensionAuthoring": { "description": "Canonical extension model for understanding and reshaping a theme from Base. Theme creation and theme editing have different permissions; see themeAuthoringModes.", "effectiveTheme": "The effective theme is Base plus a sparse theme extension. Anything not changed by the extension continues to use Base unchanged. Do not reproduce Base CSS or the complete Base variable model in a theme.", "studyBaseFirst": "Study the relevant Base implementation before extending it. Begin with Base style.css to understand assembly, use the variable contract to identify semantic controls, inspect the matching Base architecture-owner stylesheet before changing an owner, and use the class contract to reuse existing hooks.", "escalationOrder": [ "Use existing semantic QP variables wherever they truthfully express shared design decisions.", "When the brand has reusable vocabulary or mechanics Base does not own, declare theme-owned variables in theme.config.json and reuse them from semantic QP decisions or extension CSS.", "Independently evaluate the applicable published QP hooks and modifiers discovered from the canonical class and architecture contracts; use owner CSS when it materially strengthens component-specific brand expression. Variables and existing-hook CSS may be used together.", "During Creation, if an important distinction cannot be expressed through existing QP vocabulary, do not invent a theme-specific hook; emit a structured extension recommendation. During Edit, a justified theme-specific hook may be created." ], "stylesheetOwnership": "Follow stylesheetInfrastructure.ownership. Theme CSS that styles or extends a QP architecture owner MUST live in that owner's theme stylesheet; theme infrastructure may use the matching infrastructure stylesheet, including a theme-owned base.css for legitimate document-global concerns.", "generatedVariables": "All theme variable decisions are authored in theme.config.json. The compiler generates variables.css. If a generated variable is wrong, revise theme.config.json and regenerate; never patch variables.css.", "assembly": "A completed non-Base theme MUST author style.css as its canonical entry point. It imports the complete compiled Base style.css first, followed by generated theme variables.css, theme-owned infrastructure CSS when present, and architecture-owner extension stylesheets. The compiler/build produces deployable output; Base declarations are not copied into theme source." }, "siteAuthoringWorkflow": { "description": "Canonical reasoning and execution order for creating or materially revising a Quail Pages site. The sequence protects organizational truth before page, image, and visual decisions become implementation.", "principle": "Discovery seeks sufficient starting context, not permission or exhaustive interrogation. The builder is responsible for professional completeness within the discovered mandate: infer ordinary site needs from evidence, close normal completeness gaps without inventing unsupported business facts, and build the complete site implied by the job.", "steps": [ { "key": "research", "title": "Research", "description": "Orient to supplied and authoritative sources, including any existing website, public presence, content, assets, and organizational history. Do not make the person repeat knowledge already established by an appropriate source." }, { "key": "discovery", "title": "Site Discovery", "description": "Record the best current factual context, provenance, assumptions, conflicts, and unknowns. Ask only when an answer can materially change what comes next." }, { "key": "inventory-ia", "title": "Content inventory and information architecture", "description": "Inventory reusable source material and organize audience needs, content relationships, journeys, trust needs, contact paths, legal/privacy considerations, and ordinary site expectations before choosing individual pages." }, { "key": "sitemap", "title": "Sitemap and page decisions", "description": "Choose the complete page set and navigation the evidence supports. Explicitly requested pages are requirements, not necessarily a complete sitemap. Consider conventional pages such as Home, About, Contact, and Privacy where they materially support the site's purpose, trust, usability, contactability, or data practices; add other pages only when the organization, audience, content, or journeys justify them." }, { "key": "imagery", "title": "Imagery strategy", "description": "Decide what imagery must communicate, which existing assets are authoritative, what can be sourced, and where a weak substitute should be replaced by an asset request." }, { "key": "visual-direction", "title": "Visual and theme direction", "description": "Translate approved identity, desired character, references, and content needs into coordinated visual decisions. Preserve an existing site identity when the work is a migration or evolution rather than an authorized rebrand. In Site Creation without theme authority, use StyleGuide evidence only to guide content, imagery, voice, and structural interpretation; do not author theme presentation." }, { "key": "author", "title": "Author site and pages", "description": "Author the planned site and pages, not merely a representative page. Build enough real content and composition for each planned page to fulfill its purpose using known evidence, preserving unknowns rather than inventing unsupported facts. Express the result with the smallest truthful QP vocabulary." }, { "key": "theme", "title": "Select or create theme", "description": "Conditional on the resolved job. Execute this step for Theme Creation or Site + Theme Creation; skip it for Site Creation. Study Base first, then use the Theme Extension Contract for sparse semantic variable decisions in theme.config.json and architecture-owner extension CSS for coordinated art direction that variables cannot truthfully express. Generated variables.css is build output, not authored truth. A shared or site-local source must use the same compiler." }, { "key": "theme-expression-review", "title": "Theme Expression Review", "description": "Conditional on theme-authoring authority. Execute for Theme Creation, Theme Edit as applicable, or Site + Theme Creation; skip it for Site Creation. Derive the applicable user-visible presentation targets from the canonical QP architecture, class contract, and Base implementation. For each, determine the intended Style Guide expression, review the available variables and existing hooks, deliberately choose the strongest appropriate treatment, and then review the effective theme holistically for coherent brand expression." }, { "key": "validate", "title": "Validate", "description": "Validate authored documents and theme contracts, catch unresolved references and ambiguous declarations, and run freshness and type checks appropriate to the changed sources." }, { "key": "build", "title": "Build", "description": "Generate complete deployable output. Compiled stylesheets, copied theme resources, HTML, and other build output are reproducible artifacts rather than authored truth." }, { "key": "review", "title": "Review rendered result against Discovery", "description": "Inspect the actual responsive site for page-set completeness, content accuracy, working navigation/contact paths, identity fidelity, accessibility, legibility, hierarchy, imagery, and composition. Confirm ordinary planned pages were actually built, not merely identified. Feed material misses back to the owning earlier decision instead of accumulating local patches." } ], "reviewLoop": "Rendered review is part of authoring, not a post-build cosmetic check. When review exposes a mismatch, revise the earliest owning source—discovery, information architecture, content, imagery, theme contract, extension CSS, or QP architecture—and rebuild deterministically.", "jobScope": "Execute only the workflow portions authorized by the resolved authoring job. Site Creation performs site/content work but does not execute theme creation. Site + Theme Creation performs both and may iterate between them. Theme Creation and Theme Edit use the theme-authoring rules without implicitly taking ownership of site information architecture or content." }, "responsive": { "basis": "viewport-inline-size", "referencePixelsPerRem": 16, "description": "Canonical Quail Pages presentation-width vocabulary. These ranges describe available viewport inline size, not device detection. Rem boundaries are canonical; at the 16px reference size, 48rem corresponds to 768px and 64rem corresponds to 1024px. Component-owned container queries and content-fit breakpoints may use independent thresholds.", "presentations": { "mobile": { "maximumInclusiveRem": 48, "description": "Viewport inline sizes up to and including 48rem." }, "tablet": { "minimumExclusiveRem": 48, "maximumInclusiveRem": 64, "description": "Viewport inline sizes greater than 48rem and up to and including 64rem." }, "desktop": { "minimumExclusiveRem": 64, "description": "Viewport inline sizes greater than 64rem." } } }, "layers": { "description": "Canonical Quail Pages global layer vocabulary. Its system values are semantic floors that divide global z-index into architectural airspace, not general-purpose tokens for CSS behaviors that sound similar. Content remains in normal document flow and does not receive a global z-index by default; when explicit theme/content ordering is necessary, it normally stays below the first system floor (currently 0–99). Crossing a floor assigns interface to that QP-managed stratum. Components may establish local stacking contexts and use small local increments within their assigned airspace without crossing into another global layer.", "incrementGuidance": { "floorSpacing": 100, "description": "Declared global semantic floors are separated by 100 points to leave working room for small local ordering adjustments within each assigned stratum. Authors should still prefer normal painting order and local stacking contexts, and should not fill the ranges with arbitrary global values or cross another floor merely to win a stacking conflict." }, "levels": { "content": { "description": "Ordinary document content and theme-owned composition participating in normal document flow and natural painting order. Content has no declared global layer floor, CSS variable, or default z-index. When explicit ordering is necessary, themes normally remain below the persistent floor (currently 0–99); CSS behavior such as position: sticky does not by itself move an element into a managed system stratum." }, "persistent": { "floor": 100, "cssVariable": "--qp-system-layer-persistent", "description": "QP-managed viewport-persistent interface that remains available while document content moves, demonstrated by StickyTray. Persistent is an architectural role, while sticky is only a CSS behavior; theme-authored sticky content normally remains in content airspace unless it deliberately participates in this managed interface stratum." }, "overlay": { "floor": 200, "cssVariable": "--qp-system-layer-overlay", "description": "QP-managed temporary interface that must appear above persistent surfaces without taking over the page interaction context, such as popovers, disclosures, backdrops, and similar overlays. The floor reserves this semantic stratum even when no current Base component consumes it directly." }, "modal": { "floor": 300, "cssVariable": "--qp-system-layer-modal", "description": "QP-managed interface that takes over or dominates page interaction while active, demonstrated by Modal and Lightbox and also appropriate to takeover navigation." }, "system": { "floor": 400, "cssVariable": "--qp-system-layer-system", "description": "Highest QP-managed transient application/system interface, demonstrated by Toast and intended for feedback that must remain visible above ordinary interactive layers." } } }, "kinds": { "Site": { "description": "Root authored concept that defines a Quail Pages site and coordinates its site-wide configuration." }, "Page": { "description": "Root authored concept that defines an individual Quail Pages page and coordinates its layout and content." }, "Layout": { "description": "Structural authored concepts that organize pages and rendered content." }, "Rendered Content": { "description": "Authored content rendered directly through a stable Quail Pages surface." }, "Built Content": { "description": "Authored content that derives or adapts other data into rendered Quail Pages structures." }, "Custom Content": { "description": "Authored extension points resolved through reusable components or registered plugins." }, "Supporting Object": { "description": "Authored structured data consumed by another object without an independent rendering role." }, "Site Configuration": { "description": "Authored site-level structures that configure behavior, mappings, defaults, registries, and identity." }, "Core System": { "description": "Internal renderer and runtime concepts that support stable Quail Pages behavior." } }, "objects": { "PageDocument": { "kind": "Page" }, "PageHeader": { "kind": "Layout", "category": "Framing" }, "SiteHeader": { "kind": "Layout", "category": "Framing" }, "SiteFooter": { "kind": "Layout", "category": "Framing" }, "PageSection": { "kind": "Layout", "category": "Section" }, "StandardSection": { "kind": "Layout", "category": "Section" }, "RegionSection": { "kind": "Layout", "category": "Section" }, "Region": { "kind": "Layout" }, "StickyTray": { "kind": "Layout" }, "StickyTrayTriggerGroup": { "kind": "Supporting Object" }, "Card": { "kind": "Supporting Object" }, "CardList": { "kind": "Rendered Content" }, "Cta": { "kind": "Rendered Content" }, "Divider": { "kind": "Rendered Content" }, "Gallery": { "kind": "Rendered Content" }, "Image": { "kind": "Rendered Content" }, "Icon": { "kind": "Supporting Object" }, "List": { "kind": "Rendered Content" }, "Menu": { "kind": "Rendered Content" }, "Paragraph": { "kind": "Rendered Content" }, "Socials": { "kind": "Built Content" }, "Video": { "kind": "Rendered Content" }, "PageList": { "kind": "Built Content" }, "ProductList": { "kind": "Built Content" }, "Toc": { "kind": "Built Content" }, "Component": { "kind": "Custom Content", "category": "Component" }, "ComponentRef": { "kind": "Custom Content", "category": "Component" }, "PluginRef": { "kind": "Custom Content" }, "Link": { "kind": "Supporting Object" }, "MenuItem": { "kind": "Supporting Object" }, "PageCard": { "kind": "Supporting Object", "category": "Page List" }, "PageListItemSettings": { "kind": "Supporting Object", "category": "Page List" }, "ProductCard": { "kind": "Supporting Object" }, "SiteDocument": { "kind": "Site" }, "PageRoute": { "kind": "Site Configuration" }, "SiteAuthor": { "kind": "Site Configuration", "category": "Authors" }, "SiteAuthors": { "kind": "Site Configuration", "category": "Authors" }, "SiteBranding": { "kind": "Site Configuration" }, "SiteIdentity": { "kind": "Site Configuration", "category": "Identity" }, "SiteBrandIdentity": { "kind": "Site Configuration", "category": "Identity" }, "SiteIdentityIdentifier": { "kind": "Supporting Object", "category": "Identity" }, "SiteImageDefaults": { "kind": "Site Configuration" }, "PluginConfig": { "kind": "Site Configuration", "category": "Plugins" }, "SitePlugins": { "kind": "Site Configuration", "category": "Plugins" }, "SiteSocial": { "kind": "Site Configuration", "category": "Socials" }, "SiteSocials": { "kind": "Site Configuration", "category": "Socials" }, "SiteVariables": { "kind": "Site Configuration" }, "Accessibility": { "kind": "Core System" }, "Lightbox": { "kind": "Core System" }, "Modal": { "kind": "Rendered Content" }, "ModalDefinition": { "kind": "Supporting Object" }, "RuntimeStates": { "kind": "Core System" }, "Toast": { "kind": "Core System" } }, "authoringJobs": { "description": "QP work is routed by job. Determine the requested job and resolve its required authored inputs before execution. A request to build a site does not imply theme creation; theme timing is a discovery decision.", "routingPrinciple": "Start where the prerequisites require, not necessarily where the user first names the work. If a required authored specification is missing, route through its intake first. Do not silently replace a missing specification with assumptions or bypass its intake.", "jobs": { "site-intake": { "objective": "Discover and finalize the Site specification needed for Site Creation.", "inputs": [ "Available organizational evidence, existing site/content when applicable, and user answers needed to resolve material unknowns." ], "output": "Completed Site contract.", "routing": "When the user asks to build or port a site and no completed Site contract is available, begin here rather than authoring pages immediately.", "themeDecision": "During Site Intake, determine whether the user wants theme work performed now as part of Site + Theme Creation or later as a separate Theme Creation job. Do not assume either choice." }, "site-creation": { "objective": "Create or port the site structure and content into QP: information architecture, navigation, page composition, content arrangement, voice/copy, imagery decisions, and truthful QP primitive selection.", "requires": [ "Completed Site contract", "Completed StyleGuide contract" ], "styleGuideRole": "Style awareness is not styling authority. Use StyleGuide to understand voice, content emphasis, imagery, brand intent, and to distinguish intentional identity from legacy drift. Do not translate it into CSS, theme variables, custom presentation hooks, or theme-specific markup during Site Creation.", "themeAuthority": "None. The authored site must work with QP Base and remain ready for a separately created theme to be applied without restructuring content.", "outputs": [ "site.config.json", "Complete planned QP page JSON and referenced site content/assets within the site-authoring mandate." ], "routing": "If Site or StyleGuide is missing, route to the corresponding intake before Site Creation. If both exist, proceed without repeating discovery already captured there." }, "theme-creation": { "objective": "Create a complete brand-faithful QP theme by finding and fully designing the brand default for QP primitives while recommending exceptional flare that requires vocabulary beyond the existing QP contract.", "requires": [ "Completed StyleGuide contract" ], "authority": "Follow themeAuthoringModes.creation. Creation may substantially reshape Base through existing variables, published hooks, and owner CSS, but may not introduce new theme-specific structural/class hooks.", "outputs": [ "Completed theme source, including required canonical style.css assembly entry point", "Theme Build Report containing findings and structured extension recommendations when applicable." ], "routing": "If StyleGuide is missing, route through the Style Guide Intake process first. Theme Creation may be run independently or alongside Site Creation when the user chooses Site + Theme Creation." }, "theme-edit": { "objective": "Polish, update, extend, customize, refine, or otherwise evolve an existing theme, including justified exceptional flare.", "requires": [ "Existing theme", "At least one actionable edit source: explicit user instructions and/or a Theme Build Report or equivalent structured Creation handoff." ], "recommendedContext": [ "Original StyleGuide", "Original intake evidence when relevant", "Current rendered result", "User feedback on the completed theme" ], "authority": "Follow themeAuthoringModes.edit. Edit may introduce justified theme-specific classes, modifiers, variables, structural hooks, and specialized compositions after rechecking existing QP vocabulary.", "priority": "Explicit current user instructions and feedback override older Creation recommendations when they conflict." }, "site-theme-creation": { "objective": "Create the site and theme together, allowing page composition and theme-default decisions to inform one another while preserving the separate authority rules of Site Creation and Theme Creation.", "requires": [ "Completed Site contract", "Completed StyleGuide contract" ], "authority": "Site work follows site-creation authority. Theme work follows themeAuthoringModes.creation; combined execution does not grant Theme Edit permissions or authorize new custom hooks.", "reasoning": "Iterate between representative real pages and theme defaults. Use actual site compositions to test whether expressive primitive treatments are appropriate defaults. Preserve strong general-purpose defaults and recommend exceptional flare rather than encoding minority compositions as global behavior.", "outputs": [ "site.config.json", "Complete planned QP page JSON", "Completed theme source, including required canonical style.css assembly entry point", "Theme Build Report" ], "routing": "During Site Intake, ask whether theme creation should happen now with the site or later. If later, complete Site Creation using Base-compatible structure and leave theme work for a separate Theme Creation job." } }, "prerequisiteBehavior": { "rule": "A missing required authored contract is a routing condition, not permission to improvise it during downstream creation.", "siteExample": "If asked to build a site without a completed Site contract, respond by beginning Site Intake. Ensure a completed StyleGuide is also available before Site Creation. During intake, ask whether theme creation should happen now or later.", "themeExample": "If asked to create a theme without a completed StyleGuide, route through Style Guide Intake before Theme Creation.", "editExample": "If asked to edit an existing theme, explicit edit instructions are sufficient even when no Theme Build Report exists. A Creation report may instead provide the actionable instruction set, and user feedback may refine or override it." } }, "themeAuthoringModes": { "description": "QP theme work has two paths. Creation produces a complete theme using the existing QP markup/class contract and may scope extensions without implementing them. Edit starts from an existing theme and may polish, update, extend, customize, refine, or otherwise evolve it, including justified new theme-specific hooks.", "creation": { "objective": "Port the brand or intended visual identity into QP and deliver the theme as complete. Preserve identity and feel rather than reproducing a source site pixel-for-pixel unless exact reproduction is an explicit project requirement.", "allowed": [ "Reshape Base through theme.config.json overrides and theme-owned variables. Exact references assigned to Inherited variables are classified as remaps in the effective model.", "Substantially restyle, reshape, or override Base using existing QP BEM/class hooks in the matching architecture-owner stylesheet. Stylesheet placement follows stylesheetInfrastructure.ownership.", "Change layout, responsive behavior, positioning, typography, effects, surfaces, and other presentation through existing hooks.", "Record potential custom hooks as structured extension recommendations without implementing them." ], "prohibited": [ "Do not add theme-specific class hooks, modifiers, data hooks, or replacement markup solely to achieve presentation during creation.", "Do not distort the common Base treatment merely to support a minority/special-case composition.", "Do not silently resolve a missing structural distinction by inventing a custom selector contract.", "Do not aggregate CSS for multiple QP architecture owners into a theme-named or catch-all stylesheet; follow stylesheetInfrastructure.ownership." ], "completion": "Creation is not a preliminary or intentionally incomplete pass. Deliver the strongest complete brand-faithful theme possible within the existing QP structural vocabulary. Minimize architectural invention, not design effort. Complete the Theme Expression Review by exhausting the applicable presentation vocabulary from the canonical QP architecture, class contract, and Base implementation; implement the strongest truthful defaults through variables and/or existing published hooks; review the result holistically against the Style Guide; then report only meaningful extension opportunities that require vocabulary beyond the Creation boundary. A completed non-Base theme source MUST include the canonical authored style.css assembly entry point defined by stylesheetInfrastructure; omitting style.css is an incomplete Theme Creation result.", "extensionHandoff": "When existing variables and BEM hooks cannot cleanly scope an important exceptional treatment, preserve the appropriate brand default and emit a structured extension recommendation conforming to the Theme Build Report contract. The recommendation should explain the desired flare, what was attempted, why existing variables/hooks are insufficient, why applying the treatment to the standard primitive would harm or overfit the common case, and the exact class/variable/owner CSS the builder would propose.", "defaultAndFlareGuidance": { "principle": "Find the default. Fully design the default. Recommend the flare.", "description": "Theme Creation establishes and fully designs the brand's normal treatment of QP primitives before considering exceptional flare. A distinctive treatment observed in an intake, source site, or reference is evidence of a possible treatment, not evidence that it should become the primitive default.", "scopeTest": "Before adopting an expressive treatment as the theme default, ask whether ordinary instances of that primitive throughout the site should behave that way. Test the treatment against multiple representative uses when practical.", "decisionRules": [ "If the treatment remains appropriate across ordinary uses of the primitive, make it part of the theme default using existing variables, BEM/class hooks, and architecture-owner CSS.", "If QP already has a standard variation, modifier, or structural distinction that truthfully identifies the intended subset, use and style that existing vocabulary.", "If applying the treatment broadly would make ordinary uses awkward, overly expressive, less useful, or optimized around a minority composition, preserve the stronger general-purpose default.", "If the exceptional treatment cannot be scoped through existing QP vocabulary, do not introduce a new hook during Creation. Emit a structured extension recommendation instead." ], "defaultRule": "Do not optimize a primitive default for the most visually interesting example. Optimize it for the most common appropriate behavior for that brand.", "interpretation": "Creation is responsible for finding and fully designing the brand-specific default. A variable-only result is valid when deliberate review demonstrates that variables are sufficient; it is never the assumed default. Exceptional flare belongs in the handoff when it requires vocabulary beyond the existing QP contract." }, "designCompletion": { "principle": "Minimize architectural invention, not design effort.", "objective": "Express the supplied brand as faithfully as possible across the applicable QP presentation system while preserving QP architecture and using the smallest appropriate implementation. The objective is not to minimize theme-owned CSS.", "themeExpressionReview": { "required": true, "scope": "Derive review targets from the current QP architecture, class contract, Base implementation, and the primitives actually available to the theme. Do not maintain a parallel inventory here. Exhaust the applicable user-visible presentation vocabulary.", "process": [ "Determine the intended brand expression for each applicable target.", "Inspect its Base presentation, semantic variables, published hooks, modifiers, and owner stylesheet.", "Choose the smallest combination of variables and existing-hook CSS that fully expresses the brand.", "Retain Base only when its presentation is deliberately judged appropriate for the brand.", "When existing QP vocabulary cannot express an important distinction during Creation, preserve the strongest appropriate default and recommend the extension for Edit." ], "inheritanceStrategy": { "principle": "Prefer the highest appropriate existing QP variable that expresses the intended design decision, then allow the existing QP dependency graph to carry that decision downstream.", "guidance": "Do not redundantly override downstream variables when changing an upstream QP variable already produces the intended result. Override downstream variables only when the brand requires that usage to diverge from the inherited result. Introduce theme-owned vocabulary when the intended brand concept is not adequately represented by existing QP vocabulary.", "test": "Each override should represent a meaningful design decision, not merely restate a value already supplied through the effective QP dependency graph." }, "mechanismRelationship": "Variables and existing-hook CSS are complementary. Creation may substantially restyle existing QP primitives through their published hooks; the prohibition on new theme-specific hooks does not imply variable-only theming." }, "fontAssetStrategy": { "principle": "Typography is not complete merely because a font-family name is declared. A completed theme should make its intended typography available at runtime whenever licensing and available assets permit.", "assetLocation": "Bundle theme-owned font files under the theme's /fonts/ directory and reference them through the canonical QP font configuration.", "resolutionOrder": [ "Use supplied authoritative font assets when their permitted use is known and appropriate.", "When assets are not supplied, prefer obtaining the specified family from a trusted open-source source such as Google Fonts when its license permits bundling and redistribution.", "Download and bundle permitted font assets locally rather than depending on third-party runtime requests.", "Include only the families, weights, and styles needed by the theme.", "When the specified brand font cannot be legally or reliably bundled, preserve the intended font-family reference where appropriate, choose and bundle a suitable open-source fallback, and record the unresolved authoritative-font requirement in the handoff." ], "handoff": "When an authoritative font remains unresolved, clearly tell the user which font assets are still needed, why they were not bundled, what temporary fallback was chosen, and what should be replaced when the proper assets become available.", "test": "A completed theme must not silently assume that naming a font makes it available." }, "brandExpression": { "guidance": "Translate consequential visual characteristics from the Style Guide into concrete expression across the applicable QP presentation system rather than leaving them as descriptive language.", "review": "Evaluate the completed theme holistically for the visual characteristics supported by the Style Guide, including composition and interaction across responsive presentations. Use the canonical QP contracts and Base implementation to determine which surfaces and mechanisms participate; do not duplicate their vocabulary here.", "test": "The completed theme should express the intended visual character rather than merely applying brand palette and typography when the Style Guide supports stronger differentiation." }, "completion": "Ordinary uses of applicable styled QP primitives should inherit a deliberate brand-faithful default. Unchanged Base and variable-only treatment are valid outcomes of review, not assumed defaults." } }, "edit": { "objective": "Polish, update, extend, customize, refine, or otherwise evolve an existing completed theme using the original intake, current theme, builder findings/recommendations, and user feedback as evidence.", "permissions": "Edit may use all normal creation techniques and may also add justified theme-specific classes, modifiers, variables, structural hooks, and specialized compositions when the existing QP vocabulary is insufficient.", "restraint": "A builder recommendation is a hypothesis, not preapproval. Reinspect Base and the current theme before implementing it. Prefer an existing variable or BEM hook when it can now express the requirement cleanly.", "priority": "Explicit user feedback about the completed theme takes precedence over an earlier builder recommendation. Preserve parts the user approved and focus extension work on confirmed needs or clearly justified opportunities." }, "commonCaseRule": "Protect the common case. A custom hook should answer: “I cannot use the standard because …”. If an effect can be applied correctly through existing variables and BEM hooks without incorrectly changing unrelated instances, it does not justify a new hook. Minority treatments may justify a narrowly scoped extension in edit mode rather than changing the standard treatment for every instance.", "architectureFeedback": "Repeated extension recommendations for the same missing distinction across unrelated themes are evidence that the QP primitive itself may need a new standard hook or capability." } }