AGENTS.md

type	Agent Instructions
title	StyleGallery agent instructions
description	Rules coding agents must follow when editing this governed multi-domain gallery.

Agent Instructions

This repository is StyleGallery: a governed gallery with Layout, Motion, Design Engineering, Platform Guides, Design Terminology, and Expression domains, plus a free-form showcase/ work area. Read StyleGallery Domains before adding a domain, changing a domain boundary, or adapting an external source.

Before editing generated artifacts, validators, lifecycle state, or ownership policy, read Governance, Lifecycle, And Docs-As-Code.

Core Rules

• Classify every change by domain before editing.
• Keep domain-local guidance inside its owning path and preserve shared evidence boundaries.
• Do not use one domain to bypass another domain's constraints.
• Treat consumer-reference/ as shared non-domain schema, provenance, routing, and evidence infrastructure; it owns no profile values, visual defaults, component implementation, or product CSS.
• Keep dependency direction consumer/profile -> Layout. Do not import consumer-reference records, profile data, tokens, or decorative values into layout/**, patterns/**, scripts/pattern-data.mjs, or CATALOG.md.
• Include the consumer-reference handoff field in implementation handoffs. For this repository-wide agent surface use consumer_reference: consumer-reference/agent-native/registry.json; otherwise use one normalized repository-relative JSON record or not_applicable with a sentence reason.
• When an implementation handoff relies on design-terminology records, declare the term identifiers and relation types used and whether the named sources were re-checked in the session; unverified reliance must be marked as such.
• Keep material v2, v1 trust/conformance, CLI/MCP transport, and A2A/AG-UI extension planes separate. Material admission never imports profiles, source code, fixtures, schemas, tests, .omo, or visual defaults.
• Validate canonical evidence v2 against its recorded immutable Git revision. Use current-authoring source checks only when creating or finalizing new capture evidence; do not recapture merely because later repository changes differ.
• Treat consumer-reference/policies/lifecycle-dispositions.json as the lifecycle index. Preserve named owners, caller status unknown, deadlines, extension dispositions, and immutable archive bindings until their machine gate authorizes a transition.
• Treat patterns/**, recipes/**, GUIDE.md, and CATALOG.md as the Layout corpus at their existing paths.
• Treat the Layout domain as a layout pattern library, not a visual design system.
• Start with semantic HTML before adding layout classes.
• Keep DOM order, reading order, and focus order logical.
• Keep each pattern focused on one primary spatial problem.
• Allow secondary spatial behavior only when it is required for composition.
• Use the smallest robust set of CSS declarations, not the fewest fragile declarations.
• Prefer plain HTML and CSS as the source of truth.
• Make constraints explicit: widths, heights, gaps, breakpoints, scroll containers, and fixed or sticky anchors should be easy to find.
• Make scroll responsibility obvious in both class names and CSS.
• Keep decorative styling out of reusable pattern CSS.

Agent Retrieval Route

• When repository filesystem access is available, traverse the local Markdown corpus first: start at this file and README.md, follow the relevant task route or domain index, and read the selected source files directly.
• When the relevant path is not yet clear, use stylegallery search "<narrow query>" --paths-only --limit <N> to obtain a small deterministic set of repository-relative candidate paths, then continue by reading those files locally.
• Use stylegallery read <id> --outline and --section <slug> to read one part of a long document. Use stylegallery context --query as a fallback when repository files cannot be read directly or when a bounded, provenance-linked context package must be transferred to another process. Do not make context packaging the default local retrieval path.

The remaining pattern, CSS, naming, token, checklist, and verification rules apply to the Layout domain. Non-Layout domain documents may discuss product-layer behavior, but they do not authorize decorative or motion properties in reusable Layout pattern CSS.

Creative Build Route

Use this route when the task is to make a finished, expressive page (a landing page, brand study, or art-directed experiment) rather than to edit governed knowledge.

• Read only Showcase, the Expression Direction Brief, one Expression direction, and the Expression or Motion techniques the page needs. Skip governance, lifecycle, provenance, and consumer-reference documents: a showcase work creates no governed record.
• Reuse existing assets first: inspect the reference site's media, supplied files, and project assets before building a visual. Create new assets only when the intended result is graphical or vector artwork (icons, diagrams, patterns, abstract graphics, or deliberately vector illustrations). Do not generate photos, video, or realistic product renders, or imitate them with CSS/SVG/canvas stand-ins. If the needed asset is missing, find an existing one or report the missing slot; do not fabricate a replacement to pass a richness check. See Image Weight.
• Meet the richness floor measured on 49 live homepages (Measured Expression Benchmarks): existing imagery, an intentional vector graphic, or a live product surface on every screen, never a headline alone on a gradient; a 100-320ms state change on every link, button, card, tab, and media frame; masks, rounded clips, and hairlines instead of soft shadows; display type 3.5-5.5 times the body, not larger.
• Build in showcase/<slug>/ with an index.html and a brief.md. The Layout CSS Authoring, CSS Scope, Class Naming, and Token rules do not apply there. Any property, selector, library, font, or WebGL is allowed.
• Preview with bun run showcase:serve; over SSH, it prints the ssh -L command to run on the local machine. Add the work to the hub, showcase/index.html, creating the hub with the first work.
• Layout remains the floor, checked by outcome: run node scripts/check-showcase.mjs --work <slug> --richness error and fix every failure (errors, overflow, focus, reduced motion, contrast, honest actions, hash navigation, short viewports, offscreen loops, offline and no-script reading, empty screens, too few responsive elements, slow link transitions, missing masks or hairlines; see Showcase QA). Then review the settled screenshots in .tmp/showcase/<slug>/ for taste, which the check does not judge.
• A brand study of a real brand must follow Brand Studies: name the subject, mark the page Unofficial, set noindex, and use no copied logos or verbatim copy.
• Handoff: consumer_reference: not_applicable because a showcase work selects no consumer reference record.
• Promote a value or technique out of a showcase work only by writing it into an Expression or Motion page. Never copy showcase CSS into patterns/**.

Pattern Boundary Gate

Before adding a new pattern or changing reusable pattern CSS, check Layout Decision Tree and Layout Brief Template.

• Decide whether the work is a new pattern, a recipe composition, or product styling outside this repository.
• Name the layout owner, scroll owner, core layout declarations, excluded demo/product styling, and likely breaking content case.
• For scroll or responsive changes, include the failure case the pattern prevents, such as a missing shrink constraint or a viewport breakpoint used for component-local behavior.
• Add a new pattern only when existing patterns or recipes do not already cover the spatial responsibility.

CSS Authoring

• Use layout properties only unless a non-layout property is required to explain layout behavior.
• Prefer low-specificity, single-class selectors.
• Do not use ID selectors for styling or layout naming.
• Avoid deep combinators, selector chaining, element-qualified classes, and nesting unless the pattern explicitly demonstrates that tradeoff.
• Use cascade layers when the CSS surface grows beyond isolated snippets.
• Keep CSS declarations in alphabetical order inside each rule.
• Prefer intrinsic sizing and content/container-driven adaptation.
• Use viewport breakpoints only for viewport-level patterns.
• Prefer container queries for component-local responsiveness.
• Prefer logical properties for spacing and sizing unless physical direction is required.
• Use state hooks or data-* attributes for variants instead of escalating selector specificity.

CSS Scope

Allowed by default:

• align-*
• aspect-ratio
• block-size
• box-sizing
• container-*
• display
• flex-*
• gap
• grid-*
• height
• inline-size
• inset
• justify-*
• margin
• margin-block
• margin-inline
• max-*
• min-*
• overflow
• padding
• padding-block
• padding-inline
• place-*
• position
• width
• z-index

Avoid in reusable pattern CSS unless there is a layout-specific reason:

• animation
• background
• border
• border-radius
• box-shadow
• color
• filter
• font-*
• opacity
• text-*
• transition
• transform

Class Naming

• Class names must describe layout responsibility, not visual appearance.
• Class names should make relationships obvious: root-child, parent-child, area-element, and fixed-scroll relationships.
• Prefer pattern-scoped names for related nodes.
• Avoid vague names like container, wrapper, box, top, content, and bottom unless the surrounding pattern name makes their responsibility unambiguous.
• Avoid DOM-depth names that mirror every nested node; name stable roles instead.
• Do not use IDs for layout naming. Use IDs only for JavaScript hooks or document-level targets when needed.

Example:

<div class="fixed_header_layout">
    <header class="fixed_header_layout_header"></header>
    <main class="fixed_header_layout_scroll_area"></main>
</div>

Value And Token Policy

• Tokenize reusable design intent, not every layout number.
• Use tokens for stable shared values such as content width, gutters, stack gaps, section gaps, and density steps.
• Keep browser/context mechanics in raw CSS: auto, percentages, intrinsic sizing, viewport units, and container-query units.
• Put tokens behind logical CSS, for example padding-block: var(--space-4).
• Use breakpoint names for layout states, not device names.

Pattern Checklist

Before finishing a pattern change, check:

• Does the pattern optimize one primary spatial problem?
• Can the DOM structure be understood without the CSS?
• Are semantic HTML elements used before layout classes?
• Are class names semantically clear and relationship-aware?
• Is every CSS declaration necessary for robust behavior?
• Are declarations alphabetized?
• Is selector specificity low and intentional?
• Is scroll ownership explicit?
• Are constraints and change points easy to find?
• Did decorative styling stay out of the reusable pattern?

Verification Checklist

Verify the smallest relevant matrix for the change:

• Viewports: 320px, 375px, 768px, 1024px, 1440px
• Containers: tight, medium, roomy, and 100% parent
• Content: empty, short, long label, long paragraph, unbroken string
• Direction: ltr and rtl
• Writing mode: default, plus vertical writing mode if the pattern claims support
• Interaction: default, hover, focus, active, expanded, scroll top/middle/bottom when relevant

If there is no runnable gallery surface yet, inspect the snippets directly and report that manual browser verification is not available.