An open source design system that's fully customizable and agent ready
TypeScript
docs(design): seed design convention records (#5802)
Erneste678380edc76
diff --git a/docs/design/README.md b/docs/design/README.mdindex cdfdef66f8..0885614889 100644--- a/docs/design/README.md+++ b/docs/design/README.md@@ -4,6 +4,36 @@ Design specs record human-owned visual and interaction intent: hierarchy,anatomy, state representation, allowed variation, and representative examples.They may describe one component or a cross-component pattern.+## State taxonomy++State records are split by who drives the change. These are the only three+state-taxonomy records:++| Record | Owns |+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |+| [User states](user-states.md) | Person-driven rest, hover, press, focus, selection, and manipulation states |+| [System states](system-states.md) | System-driven disabled, loading, processing, status, and transient feedback states |+| [Agentic states](agentic-states.md) | Agent-driven thinking, streaming, tool execution, waiting, synchronization, inspection, and rendering states |++## Other records++| Record | Owns |+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------ |+| [Spatial hierarchy](spatial-hierarchy.md) | Perceptual grouping through proximity, spacing tiers, and alignment |+| [Control rhythm](control-rhythm.md) | Alignment and density relationships among mixed controls |+| [Shape relationships](shape-relationships.md) | Role-based and concentric geometry for nested surfaces |+| [Elevation hierarchy](elevation-hierarchy.md) | Agreement between perceived depth and actual layer order |+| [Typography hierarchy](typography-hierarchy.md) | Legible, distinguishable text roles across themes and layouts |+| [Color emphasis](color-emphasis.md) | Semantic color roles, contrast intent, and local emphasis |+| [Motion](motion.md) | Meaningful movement, timing hierarchy, easing intent, and reduced motion |+| [Ordered collection reordering](ordered-collection-reordering.md) | Drag preview, candidate insertion, commit, and settle intent for ordered collections |+| [Template composition](template-composition.md) | Page- and block-level layout, hierarchy, spacing, component fidelity, and theming |++Create a separate record when a subject has a different owner, approval+lifecycle, requirement set, evidence set, or reason to change independently.+Keep implementation mechanics, public API syntax, audit results, and consumer+usage outside these records and link to their canonical owners instead.+Design specs do not own implementation mechanics, public prop syntax, currentaudit results, or consumer usage guidance. Component and family contracts linkto stable design requirement IDs instead of copying their rationale.diff --git a/docs/design/agentic-states.md b/docs/design/agentic-states.mdnew file mode 100644index 0000000000..e0b1f90138--- /dev/null+++ b/docs/design/agentic-states.md@@ -0,0 +1,115 @@+---+schema_version: 1+template_version: 1+kind: design+id: design:agentic-states+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [ernestt, cixzhang]+review_triggers: [visual, interaction, accessibility]+verified_by: []+architecture: [architecture:theme-tokens]+components: []+families: []+deciding_specs: []+---++# Agentic states design specification++## User intent++People working with an agent should understand whether it is progressing,+waiting, inspecting, synchronizing, or presenting a result without learning a+second unrelated state language. Agent feedback should communicate actionable+system status, not expose private or hidden reasoning.++This seed record names the unresolved design surface. It intentionally does not+approve visual treatments for individual agent states.++## Design principles++- **DR1 — Extend established state language first.** Agentic states SHOULD reuse+ representations from `design:user-states` and `design:system-states` when the+ underlying intention is the same.++No additional agentic-state design requirement is approved in this seed draft.+The questions below identify areas that still require human decisions.++## Anatomy and hierarchy++The wiki does not define agentic-state anatomy or relationships. Those remain open+for a future proposal rather than being inferred by this seed draft.++## State representation++No agentic-state visual representation is approved in this seed draft.+Candidate treatments must first show why existing loading, processing, status,+selection, or temporal-overlay language is insufficient.++## Responsive and input behavior++No agentic-state responsive or input requirement is approved. Candidate+proposals must address attribution under reflow, incremental output, interruption,+and reduced motion as part of the relevant open question.++## Accessibility intent++Accessibility requirements remain unresolved with the visual treatments. Each+proposal should evaluate non-motion and non-color alternatives, announcement+frequency, focus stability, reading position, and input operability without+assuming an answer in this draft.++This record does not require disclosure of hidden chain-of-thought. Any+user-visible rationale is product content and must follow its own privacy,+safety, and content contracts.++## Representative examples++No representation is normative yet. Candidate examples should compare reuse of+existing system-state feedback with any proposed agent-specific treatment and explain+what user need the new treatment serves.++## Visual references++No normative visual assets are included. Candidate evidence should be added only+after an open question below receives a proposed treatment.++## Component contract links++No component contract links are asserted. Agent-facing components should not+claim adoption until individual state representations are decided and approved.++## Decision log++No agentic-state visual decisions have been approved. The public Design+Conventions wiki explicitly identified this area as mostly undefined; this draft+preserves that uncertainty rather than converting labels into policy.++## Open questions++- **OQ1 — Thinking or processing.** When does agent work need a representation+ distinct from ordinary system processing?+- **OQ2 — User-visible rationale.** What treatment, if any, distinguishes an+ intentionally authored explanation from ordinary output without implying+ access to hidden reasoning?+- **OQ3 — Streaming.** How should incremental text remain visibly incomplete+ without distracting from text already available?+- **OQ4 — Tool execution.** What information about backend work is useful to the+ person, and when should it remain collapsed?+- **OQ5 — Awaiting input.** How should a required human response outrank passive+ progress while preserving the surrounding task context?+- **OQ6 — Synchronizing and synchronized.** How should pending and completed+ synchronization differ from generic processing and success?+- **OQ7 — Inspecting.** Does agent inspection need a distinct state, or is+ ordinary progress plus scoped context sufficient?+- **OQ8 — Rendering.** How should generated UI communicate partial mounting and+ completion without exposing implementation churn?++## Content boundary++This file frames unresolved human-facing agentic states. It does not define agent+protocols, hidden reasoning disclosure, tool telemetry, progress-event schemas,+product copy, implementation mechanics, or approved visual treatments.diff --git a/docs/design/color-emphasis.md b/docs/design/color-emphasis.mdnew file mode 100644index 0000000000..965ee31eb7--- /dev/null+++ b/docs/design/color-emphasis.md@@ -0,0 +1,110 @@+---+schema_version: 1+template_version: 1+kind: design+id: design:color-emphasis+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [ernestt, cixzhang]+review_triggers: [visual, theming, accessibility]+verified_by: []+architecture:+ [+ architecture:theme-tokens,+ architecture:theme-authoring-contract,+ architecture:component-theming-surface,+ ]+components: []+families: []+deciding_specs: []+---++# Color emphasis design specification++## User intent++People should find the primary action and understand surface and status roles+without decoding arbitrary colors. Color should preserve legibility and hierarchy+across supported modes and themes.++## Design principles++- **DR1 — Foreground and background are one decision.** A color choice MUST be+ evaluated in the context of the surface it sits on.+- **DR2 — Neutral color follows semantic role.** Interaction overlays, tracks,+ content containers, and self-contained elements MUST remain distinguishable+ even when their neutral values look similar.+- **DR3 — Emphasis remains scarce.** A local action group SHOULD expose one clear+ primary emphasis rather than making every action compete equally.+- **DR4 — Status follows its canonical feedback contract.** Color emphasis MUST+ preserve the non-color cues and prominence defined by+ `design:system-states` rather than inventing another status treatment.+- **DR5 — Interaction overlays preserve context.** Hover and press treatment+ SHOULD visually combine with the underlying surface rather than replace it with+ an unrelated opaque block.++## Anatomy and hierarchy++| Role | Purpose | Required relationship |+| ---------------- | ---------------------------------------------------- | ----------------------------------------------------------- |+| base surface | Establishes page, container, or element context | Determines the meaning and legibility of foreground choices |+| foreground | Carries text, icon, or boundary information | Remains legible against its paired surface |+| interaction tint | Communicates transient response | Preserves the identity of the underlying surface |+| primary accent | Directs attention to the most important local action | Remains visually stronger than peer actions |++## State representation++Rest, hover, press, focus, selected, and disabled states MUST remain perceptually+distinct in every supported mode. Status representation is owned by+`design:system-states`. Supporting and disabled text MUST not become+indistinguishable merely because both are quieter than body text.++## Responsive and input behavior++- **DR6 — Emphasis survives density.** When actions collapse or move, the primary+ action MUST remain identifiable without amplifying every remaining control.+- **DR7 — Hover color is optional feedback.** Touch and keyboard paths MUST retain+ state meaning without depending on hover tint.++## Accessibility intent++Foreground/background pairs must remain legible across supported modes. Color+emphasis must not weaken the non-color status cues owned by+`design:system-states`. Exact thresholds and mechanical contrast+verification remain accessibility and audit responsibilities.++## Representative examples++- A toolbar exposes one primary action while secondary and destructive actions+ remain clear without sharing the same emphasis.++## Visual references++No normative assets are included. Action hierarchy and semantic-neutral examples+should be added under `docs/design/assets/color-emphasis/` before promotion.+Status examples remain with `design:system-states`.++## Component contract links++No component links are asserted in this seed draft.++## Decision log++No repository design decision has approved this record yet. It distills color+role and emphasis intent from the public Design Conventions wiki while delegating+token vocabulary and theme mechanics to architecture.++## Open questions++- **OQ1 — Primary-action scope.** Which containers reset the local primary-action+ hierarchy?+- **OQ2 — Representative themes.** Which themes and modes form the minimum+ evidence set for role preservation?++## Content boundary++This file defines color role and emphasis. It does not define token names, raw+values, contrast thresholds, theme APIs, component props, or audit checks.diff --git a/docs/design/control-rhythm.md b/docs/design/control-rhythm.mdnew file mode 100644index 0000000000..5c0f674f67--- /dev/null+++ b/docs/design/control-rhythm.md@@ -0,0 +1,98 @@+---+schema_version: 1+template_version: 1+kind: design+id: design:control-rhythm+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [ernestt, cixzhang]+review_triggers: [visual, layout, accessibility]+verified_by: []+architecture: [architecture:theme-tokens]+components: []+families: [family:input-fields]+deciding_specs: []+---++# Control rhythm design specification++## User intent++Mixed controls should feel intentionally composed rather than assembled from+unrelated sizing systems. Visual compactness should not make an interaction+unreasonably difficult to target.++## Design principles++- **DR1 — Mixed controls align.** Fixed-height and content-sized controls used in+ one row MUST share an intentional baseline and apparent height.+- **DR2 — Size and density are tuned together.** Authors MUST evaluate outer size+ and internal padding as one visual rhythm rather than independent settings.+- **DR3 — Content has breathing room.** Text and icons MUST retain enough internal+ space to remain legible and visually centered.+- **DR4 — Visual size and target size serve different needs.** A control MAY look+ compact while preserving an operable target appropriate to its input context.++## Anatomy and hierarchy++| Role | Purpose | Required relationship |+| --------------------- | ---------------------------------- | ----------------------------------------------------------- |+| fixed control | Provides a predictable silhouette | Aligns with peer controls at the selected size |+| content-sized control | Accommodates variable text or rows | Tunes density to the surrounding rhythm |+| content lane | Holds text and icons | Remains centered and free from edge crowding |+| target area | Receives interaction | May exceed the visible silhouette without disrupting layout |++## State representation++Rest, focus, loading, value, and status states MUST preserve the intended row+height and alignment unless the component contract explicitly defines expansion.++## Responsive and input behavior++- **DR5 — Rows remain coherent under constraint.** Controls MAY wrap or stack, but+ each resulting row MUST retain deliberate alignment.+- **DR6 — Input context informs targets.** Compact pointer layouts MAY differ+ visually from touch-oriented layouts while preserving the same control identity.++## Accessibility intent++Compact treatment must not compromise readability, focus visibility, or+operability. Target-size mechanics and minimum thresholds remain with component,+accessibility, and audit contracts.++## Representative examples++- A medium action and default-density field in one toolbar land on the same+ apparent height and baseline.+- A compact icon control retains a larger operable target than its glyph suggests.++## Visual references++No normative assets are included. Mixed field/action and pointer/touch examples+should be added under `docs/design/assets/control-rhythm/` before promotion.++## Component contract links++No component links are asserted. `family:input-fields` is a candidate relationship+pending adoption review.++## Decision log++No repository design decision has approved this record yet. It distills the+size-and-density intent from the public Design Conventions wiki.++## Open questions++- **OQ1 — Target intent.** The source material describes a generous touch target+ but a much smaller audit failure threshold. The design target and mechanical+ floor need separate definitions.+- **OQ2 — Reference row.** Which control combination should provide normative+ visual evidence for each supported density?++## Content boundary++This file defines perceived rhythm and target intent. It does not define size+values, density props, padding tokens, hit-area mechanics, or audit thresholds.diff --git a/docs/design/elevation-hierarchy.md b/docs/design/elevation-hierarchy.mdnew file mode 100644index 0000000000..700de1049c--- /dev/null+++ b/docs/design/elevation-hierarchy.md@@ -0,0 +1,101 @@+---+schema_version: 1+template_version: 1+kind: design+id: design:elevation-hierarchy+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [ernestt, cixzhang]+review_triggers: [visual, interaction, theming]+verified_by: []+architecture: [architecture:layer-runtime, architecture:theme-tokens]+components: []+families: [family:overlay-dismissal]+deciding_specs: []+---++# Elevation hierarchy design specification++## User intent++People should understand which surface is above another without noticing an+overbuilt shadow system. A surface that looks higher should also cover lower+content and remain unclipped.++## Design principles++- **DR1 — Perceived and actual order agree.** A surface that appears higher MUST+ behave as the higher layer.+- **DR2 — Depth remains quiet.** Shadows and edges SHOULD communicate separation+ without becoming the dominant visual feature.+- **DR3 — One edge language leads.** A surface SHOULD use either a defined edge or+ soft elevation as its primary boundary rather than combining both at full+ strength.+- **DR4 — State rings are not elevation.** Input and focus rings MUST remain+ visually distinct from shadows that communicate layer depth.++## Anatomy and hierarchy++| Role | Purpose | Required relationship |+| ---------------- | -------------------------------------------- | ------------------------------------------------ |+| base content | Establishes the reference plane | Remains beneath temporary and floating surfaces |+| floating surface | Presents content above the base | Uses depth appropriate to its interaction role |+| boundary cue | Separates the surface from what is behind it | Supports rather than competes with elevation |+| escape path | Allows a floating surface to remain visible | Prevents unintended clipping by lower containers |++## State representation++Resting content, floating menus, persistent overlays, and transient feedback MUST+form a coherent depth sequence. Focus or validation rings MUST NOT imply that a+control moved to another layer.++## Responsive and input behavior++- **DR5 — Depth survives repositioning.** A surface MAY move or resize to fit the+ viewport, but its perceived place in the hierarchy MUST remain stable.+- **DR6 — Floating content escapes containers.** Responsive clipping or scrolling+ MUST NOT make a surface appear underneath content it is meant to cover.++## Accessibility intent++Layer order must remain understandable through focus movement, semantics, and+content relationship, not shadow alone. High-contrast presentation should retain+clear boundaries even when soft shadows are unavailable.++## Representative examples++- A menu appears above its trigger and nearby sticky content without an exaggerated+ shadow.+- A modal and transient notification preserve their relative hierarchy when the+ viewport becomes constrained.++## Visual references++No normative assets are included. Representative layer combinations should be+added under `docs/design/assets/elevation-hierarchy/` before promotion.++## Component contract links++No component links are asserted. `family:overlay-dismissal` is a candidate+relationship for review, not an adoption claim.++## Decision log++No repository design decision has approved this record yet. It distills the+perceptual elevation intent from the public Design Conventions wiki and delegates+stacking mechanics to `architecture:layer-runtime`.++## Open questions++- **OQ1 — Boundary balance.** Which surface archetypes intentionally combine a+ subtle edge and shadow?+- **OQ2 — Evidence set.** Which nested layer sequence should be the normative+ visual and behavioral example?++## Content boundary++This file defines perceived depth. It does not define z-index values, portals,+layer allocation, overflow mechanics, shadow tokens, or dismissal behavior.diff --git a/docs/design/motion.md b/docs/design/motion.mdnew file mode 100644index 0000000000..fc50424d27--- /dev/null+++ b/docs/design/motion.md@@ -0,0 +1,102 @@+---+schema_version: 1+template_version: 1+kind: design+id: design:motion+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [ernestt, cixzhang]+review_triggers: [visual, interaction, accessibility, motion]+verified_by: []+architecture: [architecture:theme-tokens]+components: []+families: []+deciding_specs: []+---++# Motion design specification++## User intent++Movement should clarify what changed and where content came from without making a+surface feel theatrical or sluggish. Every state change should remain understandable+when motion is reduced.++## Design principles++- **DR1 — Motion carries meaning.** Animation MUST explain response, continuity,+ entry, exit, or spatial change rather than decorate otherwise static content.+- **DR2 — Weight determines timing.** Small local feedback SHOULD feel faster+ than large entrances, exits, or continuous movement.+- **DR3 — Movement settles naturally.** Easing SHOULD communicate controlled+ deceleration rather than ornamental bounce or elasticity.+- **DR4 — Stable content stays stable.** Motion SHOULD avoid unnecessary layout+ disruption and preserve reading and interaction context.+- **DR5 — Reduced motion preserves meaning.** Every animated transition MUST have+ an immediate or minimally moving form that communicates the same state change.++## Anatomy and hierarchy++| Role | Purpose | Required relationship |+| ------------------- | ------------------------------------------- | --------------------------------------------------- |+| origin state | Establishes what is changing | Remains identifiable until continuity is clear |+| transition cue | Connects origin and destination | Uses only the movement needed to explain the change |+| destination state | Shows the completed result | Settles without residual decorative activity |+| reduced-motion path | Communicates the same result without travel | Preserves timing and status meaning where needed |++## State representation++Hover and press use the lightest useful response; entrances and exits may use a+more visible transition; large or continuous movement requires stronger user+justification. Loading and status MUST remain understandable without animation.++## Responsive and input behavior++The source wiki does not establish responsive-path, interruption, or+input-specific motion rules beyond the principles above. Those concerns remain+open for separately evidenced decisions.++## Accessibility intent++Motion must not be required to perceive status, hierarchy, or completion. Reduced+motion should suppress unnecessary travel while preserving feedback. Animated+content should not repeatedly steal attention from reading or input.++## Representative examples++- A pressed control responds immediately without launching decorative movement.+- A surface entrance explains where new content belongs, then settles quietly.+- Reduced-motion mode shows the same completed state without spatial travel.++## Visual references++No normative assets are included. Micro-interaction, entrance/exit, and+reduced-motion pairs should be added under `docs/design/assets/motion/` before+promotion.++## Component contract links++No component links are asserted in this seed draft.++## Decision log++No repository design decision has approved this record yet. It distills motion+intent from the public Design Conventions wiki without copying duration values,+CSS properties, or audit mechanics.++## Open questions++- **OQ1 — Reference transitions.** Which component interactions should be the+ normative examples for local, entrance/exit, and large movement?+- **OQ2 — Interruption and reflow.** What requirements should govern reversing,+ cancelling, replacing, or responsively reflowing an active transition?+- **OQ3 — Allowed expressive motion.** Which product contexts, if any, justify a+ deliberately expressive treatment beyond functional continuity?++## Content boundary++This file defines motion intent. It does not define duration or easing tokens,+CSS properties, animation APIs, component behavior, or audit checks.diff --git a/docs/design/ordered-collection-reordering.md b/docs/design/ordered-collection-reordering.mdnew file mode 100644index 0000000000..75bf4129c6--- /dev/null+++ b/docs/design/ordered-collection-reordering.md@@ -0,0 +1,132 @@+---+schema_version: 1+template_version: 1+kind: design+id: design:ordered-collection-reordering+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [ernestt, cixzhang]+review_triggers: [visual, interaction, accessibility, motion]+verified_by: []+architecture: [architecture:interaction-modality, architecture:theme-tokens]+components: []+families: []+deciding_specs: []+---++# Ordered collection reordering design specification++## User intent++A person reordering a list or row collection should understand what is moving,+where it will land, and when the change is committed. Pointer and keyboard paths+should communicate the same candidate position without making surrounding items+jump prematurely.++This treatment is for changing order within a collection. Freeform canvas+placement and file-drop targets require separate design specifications.++## Design principles++- **DR1 — Reordering begins from an explicit handle.** The interaction MUST start+ from a dedicated affordance so activation is intentional and other item+ actions remain available.+- **DR2 — The moving item remains recognizable without appearing elevated.** The+ source and pointer-following preview MUST read as the same item in a temporary+ moving state and MUST NOT imply a raised card.+- **DR3 — Placement is previewed before the collection changes.** A clear+ insertion cue MUST mark the candidate position while surrounding items remain+ stable until commit.+- **DR4 — Commit happens once.** The collection MUST adopt the new order on drop+ or release rather than repeatedly committing as the pointer crosses items.+- **DR5 — Completion restores normal hierarchy.** Temporary drag treatment MUST+ disappear immediately on drop or cancel, and settled items MUST return to+ their normal contrast and depth.++## Anatomy and hierarchy++| Role | Purpose | Required relationship |+| ------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------- |+| reorder handle | Starts and retains ownership of the interaction | Belongs to one item and remains distinguishable from item activation |+| stationary source | Preserves the item's origin during active drag | Remains in place until commit and shares temporary treatment with the preview |+| moving preview | Follows pointer movement | Duplicates the source identity without adding raised-card elevation |+| insertion cue | Marks the candidate ordered position | Appears between items on the collection's ordering axis |+| surrounding items | Provide stable spatial context | Do not shift until the reorder is committed |+| settled collection | Shows the resulting order | Returns every item to its normal state after completion |++## State representation++| State | Required representation | Allowed variation |+| ------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------------------- |+| rest | The handle is discoverable without overpowering item content | Handle placement may follow the collection family |+| dragging | Source and moving preview use the same temporary reduced-emphasis treatment | Pointer preview may move freely on both axes |+| candidate position | A clear accent insertion line marks where the item will land | Line length and inset may follow row geometry |+| dropped | Items settle into the committed order and temporary drag treatment clears | Settling motion may use the system's fast movement language |+| cancelled | Original order and normal contrast return immediately | Cancellation may be immediate even when normal motion is enabled |++## Responsive and input behavior++- **DR6 — Placement follows the collection axis.** Pointer previews MAY move+ freely, while candidate order MUST be calculated on the collection's ordering+ axis.+- **DR7 — Keyboard and pointer share the insertion cue.** Keyboard reordering+ MUST expose the same candidate-position representation as pointer reordering.+- **DR8 — Reduced motion updates directly.** When motion is reduced, the final+ order MUST update without animated travel.++## Accessibility intent++Focus should remain with the reorder handle throughout the operation. Position+changes, cancellation, and completion should be announced in terms a person can+understand without seeing the preview. The temporary reduced-emphasis treatment+is acceptable only during active reordering and must not reduce the persistent+legibility of content.++Focus mechanics, keyboard commands, live-region wording, and collection mutation+belong to component and family contracts.++## Representative examples++- A row starts moving from its handle; the original row and pointer preview+ become temporarily quieter while a line marks the candidate gap.+- Keyboard movement changes the same insertion cue one position at a time while+ focus remains on the handle.+- Dropping commits once, then the collection settles into the new order.++## Visual references++No normative assets are included in this seed draft. Pointer and keyboard+sequences should be added under+`docs/design/assets/ordered-collection-reordering/` before promotion.++## Component contract links++No component contract links are asserted in this seed draft. A collection+component should link these requirements only after its input and accessibility+contracts define reordering semantics.++## Decision log++No repository design decision has approved this record yet. The draft isolates+the reordering treatment from the broader user-state vocabulary so its distinct+interaction and accessibility requirements can be reviewed independently.++## Open questions++- **OQ1 — Preview treatment.** Does reduced emphasis for both stationary source+ and moving preview remain appropriate across light, dark, and high-contrast+ themes?+- **OQ2 — Insertion geometry.** Which collection families need a deliberate+ exception to the default between-item insertion line?+- **OQ3 — Representative owner.** Which component or family should provide the+ canonical pointer and keyboard evidence?++## Content boundary++This file defines the visual and interaction intent of ordered reordering. It+does not define event handling, keyboard commands, focus implementation,+announcement strings, list mutation, token names, canvas placement, or file-drop+behavior.diff --git a/docs/design/shape-relationships.md b/docs/design/shape-relationships.mdnew file mode 100644index 0000000000..2dd8e134a1--- /dev/null+++ b/docs/design/shape-relationships.md@@ -0,0 +1,97 @@+---+schema_version: 1+template_version: 1+kind: design+id: design:shape-relationships+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [ernestt, cixzhang]+review_triggers: [visual, theming, layout]+verified_by: []+architecture: [architecture:theme-tokens, architecture:theme-authoring-contract]+components: []+families: []+deciding_specs: []+---++# Shape relationships design specification++## User intent++Nested surfaces should read as parts of one intentional shape. Inner corners+should not visually fight their container, and decorative accents should not+break the geometry of rounded surfaces.++## Design principles++- **DR1 — Radius follows role.** Corner character MUST reflect whether an element+ is inner content, a control, a container, a page region, or a fully rounded form.+- **DR2 — Nested curves remain concentric.** Inner and outer corners MUST read as+ parallel shapes after accounting for the space between them.+- **DR3 — Shape character is systemic.** Themes SHOULD tune overall sharpness or+ roundness coherently rather than override isolated elements.+- **DR4 — Accents respect geometry.** Borders and edge accents MUST integrate with+ the corner shape instead of visibly colliding with it.++## Anatomy and hierarchy++| Role | Purpose | Required relationship |+| ----------------- | --------------------------------- | ------------------------------------------------------------------- |+| outer surface | Establishes the containing shape | Determines the curve available to nested content |+| intervening space | Separates nested boundaries | Visually accounts for the difference between outer and inner curves |+| inner surface | Continues the containing geometry | Reads as concentric with the outer surface |+| accent edge | Adds emphasis or status | Follows rather than interrupts the surface shape |++## State representation++Hover, focus, selection, and status borders MUST preserve the base geometry.+Changing state must not introduce a conflicting corner system.++## Responsive and input behavior++- **DR5 — Shape survives resizing.** Responsive changes MAY alter dimensions, but+ nested corner relationships MUST remain coherent.+- **DR6 — State rings follow the owner.** Focus or selection treatments MUST trace+ the visible owning shape without producing doubled or mismatched curves.++## Accessibility intent++Shape should reinforce boundaries and ownership but must not be the only signal+for state or grouping. Focus and status remain perceivable independent of corner+style.++## Representative examples++- A nested panel's inner curve follows its container and intervening space.+- A selected rounded card receives an integrated boundary rather than a thick+ side stripe that collides with its corners.++## Visual references++No normative assets are included. Nested and stateful examples should be added+under `docs/design/assets/shape-relationships/` before promotion.++## Component contract links++No component links are asserted in this seed draft.++## Decision log++No repository design decision has approved this record yet. It distills the+concentric-shape intent from the public Design Conventions wiki without copying+radius values or calculations.++## Open questions++- **OQ1 — Allowed exceptions.** Which components intentionally break concentric+ geometry because their content or clipping model requires it?+- **OQ2 — Evidence set.** Which nested surfaces and themes best demonstrate the+ relationship across sharp and rounded theme personalities?++## Content boundary++This file defines perceptual shape relationships. It does not define radius token+values, formulas, CSS, theme APIs, border widths, or audit checks.diff --git a/docs/design/spatial-hierarchy.md b/docs/design/spatial-hierarchy.mdnew file mode 100644index 0000000000..469a10cb7f--- /dev/null+++ b/docs/design/spatial-hierarchy.md@@ -0,0 +1,99 @@+---+schema_version: 1+template_version: 1+kind: design+id: design:spatial-hierarchy+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [ernestt, cixzhang]+review_triggers: [visual, layout, responsive]+verified_by: []+architecture: [architecture:container-padding, architecture:theme-tokens]+components: []+families: [family:layout-primitives, family:layout-regions]+deciding_specs: []+---++# Spatial hierarchy design specification++## User intent++People should understand what belongs together before reading individual labels.+A dense surface should remain organized because proximity expresses relationship,+not because every group is enclosed by another container.++## Design principles++- **DR1 — Proximity communicates relationship.** Closely related elements MUST+ sit closer than separate concerns.+- **DR2 — Separation grows with grouping level.** Gaps MUST increase from local+ content to groups and from groups to sections.+- **DR3 — Space precedes containment.** Authors SHOULD use spacing and alignment+ to establish groups before adding another card or boundary.+- **DR4 — Variation is intentional.** A composition MUST use enough spatial+ contrast to reveal its hierarchy rather than applying one gap everywhere.++## Anatomy and hierarchy++| Role | Purpose | Required relationship |+| -------------- | ----------------------------------------------------------- | ---------------------------------------------------------- |+| local gap | Joins a label, value, icon, or control to immediate content | Smaller than its containing group gap |+| group gap | Separates peer controls or content groups | Larger than local gaps and smaller than section separation |+| section gap | Separates distinct concerns | Strong enough to survive the squint test |+| alignment edge | Connects related content across rows or regions | Repeats consistently within the same grouping level |++## State representation++Spatial relationships MUST remain perceptible in populated, sparse, empty, and+error states. Conditional content must not collapse or invert the grouping order.++## Responsive and input behavior++- **DR5 — Reflow preserves grouping.** At constrained widths, content MAY stack or+ move, but local, group, and section relationships MUST remain distinguishable.+- **DR6 — Dynamic content preserves rhythm.** Validation, supporting text, and+ optional actions MUST remain associated with the content they serve.++## Accessibility intent++Visual grouping should agree with semantic reading order and programmatic+relationships. Space must not be the only signal when a group requires a label,+heading, or other semantic boundary.++## Representative examples++- A form uses its tightest relationship between label and field, a larger gap+ between fields, and the largest gap between sections.+- A dashboard separates regions through spacing and alignment before adding+ nested cards.++## Visual references++No normative assets are included. Wide and constrained examples should be added+under `docs/design/assets/spatial-hierarchy/` before promotion.++## Component contract links++No component links are asserted. The listed layout families are candidate+relationships pending adoption review.++## Decision log++No repository design decision has approved this record yet. It distills the+spacing intent from the public Design Conventions wiki without copying token+values or audit thresholds.++## Open questions++- **OQ1 — Evidence set.** Which page, form, and collection examples best verify+ each grouping level?+- **OQ2 — Containment exception.** Which component families require visible+ containment in addition to spatial grouping?++## Content boundary++This file defines perceptual grouping. It does not define spacing token values,+padding algorithms, component props, DOM structure, or audit scoring.diff --git a/docs/design/system-states.md b/docs/design/system-states.mdnew file mode 100644index 0000000000..e6be1ea8ba--- /dev/null+++ b/docs/design/system-states.md@@ -0,0 +1,124 @@+---+schema_version: 1+template_version: 1+kind: design+id: design:system-states+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [ernestt, cixzhang]+review_triggers: [visual, interaction, accessibility]+verified_by: []+architecture: [architecture:theme-tokens]+components: []+families: [family:input-fields, family:overlay-dismissal]+deciding_specs: []+---++# System states design specification++## User intent++A person should distinguish unavailable, waiting, processing, successful,+warning, informational, and error conditions without relying on color alone.+Feedback should use prominence appropriate to its persistence and urgency while+preserving surrounding layout.++## Design principles++- **DR1 — System state preserves context.** Loading, processing, and status+ treatments MUST keep enough of the original component's geometry and identity+ for the person to understand what is affected.+- **DR2 — Status meaning survives color.** Every semantic status MUST pair color+ with an icon, label, or other non-color signal.+- **DR3 — Prominence follows persistence and urgency.** Persistent in-flow+ feedback SHOULD remain quiet, compact or urgent feedback MAY use a solid+ treatment, and brief transient feedback MAY use an inverted overlay.+- **DR4 — One meaning remains recognizable across tiers.** Changing prominence+ MUST NOT change the underlying success, information, warning, or error meaning.+- **DR5 — Busy states do not cause layout shift.** Placeholder and processing+ representations MUST preserve the affected content's expected dimensions.++## Anatomy and hierarchy++| Role | Purpose | Required relationship |+| ----------------------- | ---------------------------------------------------- | -------------------------------------------------------- |+| affected surface | Shows what is disabled, waiting, or reporting status | Retains enough geometry to preserve context |+| progress representation | Shows that content or an action is unresolved | Fits the scope and duration of the wait |+| semantic indicator | Communicates feedback category | Pairs color with icon, label, or equivalent cue |+| supporting message | Explains reason, consequence, or next action | Remains associated with the affected surface |+| prominence container | Scales feedback from in-flow to transient | Matches persistence and urgency without changing meaning |++## State representation++| State | Required representation | Allowed variation |+| -------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |+| disabled | Muted, clearly unavailable, and non-interactive; a reason remains available when needed | Components may place the reason according to their family contract |+| loading, placeholder | A stable skeleton or structural placeholder stands in for content not yet available | Shape follows the expected content |+| processing, in place | A progress indicator appears without changing the control's dimensions | Indicator may replace or accompany content when identity remains clear |+| status, muted | A quiet semantic surface combines status color with icon or text | Used for persistent banners, fields, and in-flow feedback |+| status, solid | A high-prominence semantic fill combines status color with contrasting content | Used for compact labels or urgent feedback |+| temporal overlay | A brief inverted surface appears above current content and dismisses | Used for transient messages and explanatory overlays |++## Responsive and input behavior++- **DR6 — Feedback remains attached under reflow.** Supporting messages and+ progress representations MUST remain associated with the affected content at+ narrow widths and across orientation changes.+- **DR7 — Transient feedback remains operable.** Responsive placement MUST NOT+ hide dismissal, pause, or follow-up actions where those actions exist.+- **DR8 — Busy feedback does not depend on motion.** Reduced-motion mode MUST+ still communicate that work is pending.++## Accessibility intent++A person should be able to identify status category, affected scope, and any+available next action without color perception or animation. Disabled reasons+should remain reachable without enabling the blocked action. Busy content should+communicate that it is unresolved without repeatedly disrupting reading or focus.++ARIA mapping, disabled semantics, busy behavior, dismissal, timing, and live+announcements remain component and family responsibilities.++## Representative examples++- A field processing a value keeps its width and label while a progress indicator+ occupies an established end lane.+- A persistent warning uses a quiet in-flow surface with an icon and message.+- An urgent transient error uses stronger prominence but preserves the same error+ meaning and icon language.++## Visual references++No normative assets are included in this seed draft. Representative disabled,+loading, muted, solid, and transient states should be added under+`docs/design/assets/system-states/` before promotion.++## Component contract links++No component contract links are asserted in this seed draft. The listed family+relationships are candidates for review, not claims that those draft or current+contracts have adopted these requirements.++## Decision log++No repository design decision has approved this record yet. It distills the+system-driven state and prominence vocabulary from the public Design Conventions+wiki while leaving semantics and mechanics with components and families.++## Open questions++- **OQ1 — Tier selection.** Which status surfaces have fixed prominence, and+ which may vary based on product context or severity?+- **OQ2 — Processing distinction.** When should an unresolved surface use a+ structural placeholder versus an in-place progress indicator?+- **OQ3 — Temporal boundary.** Which transient feedback belongs in this shared+ vocabulary versus a dedicated overlay or notification design record?++## Content boundary++This file defines visual distinctions and prominence for system-driven feedback.+It does not define prop names, ARIA attributes, loading semantics, dismissal or+timing behavior, token names, audit checks, or consumer usage.diff --git a/docs/design/template-composition.md b/docs/design/template-composition.mdnew file mode 100644index 0000000000..f4daead44f--- /dev/null+++ b/docs/design/template-composition.md@@ -0,0 +1,133 @@+---+schema_version: 1+template_version: 1+kind: design+id: design:template-composition+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [ernestt, cixzhang]+review_triggers: [visual, layout, theming, responsive]+verified_by: []+architecture:+ [+ architecture:component-theming-surface,+ architecture:container-padding,+ architecture:theme-tokens,+ ]+components: []+families: [family:layout-primitives, family:layout-regions]+deciding_specs: []+---++# Template composition design specification++## User intent++A page template or reusable block should look like an intentional product+surface, not merely a valid collection of components. It should establish a+clear reading order, coherent regions, and theme-safe emphasis while leaving+product content and application chrome to the adopting product.++## Design principles++- **DR1 — Layout communicates purpose.** Structural regions, grid, and stacking+ MUST make the page's primary task apparent before individual content is read.+- **DR2 — Visual hierarchy directs the eye.** Size, weight, and placement MUST+ establish an intentional path from page context to primary content and action.+- **DR3 — Spacing and alignment express relationships.** Repeated edges, gaps,+ and grouping tiers MUST remain coherent across the whole composition.+- **DR4 — Components preserve their affordances.** A template MUST choose+ components and variants whose visual language matches the intended action,+ navigation, data, or status role.+- **DR5 — Color and theming preserve hierarchy.** Surface and accent choices MUST+ retain meaning and emphasis in every supported theme and color mode.++## Anatomy and hierarchy++| Role | Purpose | Required relationship |+| ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------ |+| page context | Establishes where the person is and what the surface is for | Leads the visual hierarchy without competing with the primary task |+| structural region | Groups navigation, controls, content, or supporting information | Uses layout boundaries and spacing that match its role |+| primary content | Carries the page's main task or information | Receives the strongest sustained hierarchy |+| primary action | Offers the most important local next step | Remains singular and easy to identify within its action group |+| supporting content | Adds explanation, metadata, or secondary action | Remains available without flattening hierarchy |+| repeated item | Forms a list, grid, table, or card collection | Preserves alignment and rhythm across realistic content variation |++## State representation++| State | Required representation | Allowed variation |+| ------------------ | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |+| populated | Regions and hierarchy remain clear with realistic content | Content length and collection size may vary within the template's purpose |+| sparse | Empty space preserves intentional grouping rather than collapsing structure | Optional supporting regions may disappear |+| constrained | Regions reflow without losing reading order or primary action | Navigation and secondary content may move or collapse according to family contracts |+| light or dark mode | Surface hierarchy, contrast, and accent meaning remain intact | Theme controls palette and visual personality |+| interactive | Component states remain recognizable inside the larger composition | Components retain their family-owned treatments |++## Responsive and input behavior++- **DR6 — Reflow preserves reading order.** Responsive changes MUST retain the+ relationship among page context, primary content, supporting regions, and+ actions.+- **DR7 — Collections adapt without arbitrary clipping.** Repeated content MUST+ use a layout strategy that remains coherent across supported widths and+ realistic item lengths.+- **DR8 — Input modes keep the same task hierarchy.** Keyboard, pointer, and+ touch paths MUST reach the same primary task and actions without relying on+ hover-only discovery.++## Accessibility intent++Visual hierarchy should agree with semantic reading and focus order. Reflow must+not separate labels, explanations, errors, or actions from the content they+serve. Theme variation must preserve legibility and state meaning, and realistic+content must not expose inaccessible overflow or truncation.++Semantic markup, component APIs, focus management, and responsive implementation+belong to components, layout families, and consumer guidance.++## Representative examples++- A dense data page still exposes one clear title, control region, primary data+ region, and action hierarchy when viewed at a glance.+- A card collection retains alignment and grouping with realistic titles,+ metadata, and missing optional content.+- A narrow layout moves supporting regions without changing reading order or+ hiding the primary action.++## Visual references++No normative assets are included in this seed draft. Representative full-page+and block examples should be added under+`docs/design/assets/template-composition/` in light, dark, wide, and constrained+states before promotion.++## Component contract links++No component contract links are asserted. The listed layout-family relationships+are candidates for review; consumer templates remain responsible for using the+public contracts those families expose.++## Decision log++No repository design decision has approved this record yet. This draft migrates+only the human visual-quality axes from the public Design Conventions wiki; it+deliberately excludes authoring mechanics and audit grading.++## Open questions++- **OQ1 — Representative templates.** Which page templates and blocks should be+ normative examples for each composition requirement?+- **OQ2 — Product chrome boundary.** Which structural regions belong to a+ reusable page template versus the host application?+- **OQ3 — Evidence.** How should screenshot review demonstrate hierarchy and+ composition without turning subjective judgment into a misleading score?++## Content boundary++This file defines human visual intent for template composition. It does not+define required React components, raw-HTML policy, icon plumbing, styling+mechanics, mock-data sources, documentation metadata, line-count targets, audit+grades, or consumer instructions.diff --git a/docs/design/typography-hierarchy.md b/docs/design/typography-hierarchy.mdnew file mode 100644index 0000000000..df6275a5bd--- /dev/null+++ b/docs/design/typography-hierarchy.md@@ -0,0 +1,104 @@+---+schema_version: 1+template_version: 1+kind: design+id: design:typography-hierarchy+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [ernestt, cixzhang]+review_triggers: [visual, theming, accessibility]+verified_by: []+architecture: [architecture:theme-tokens, architecture:theme-authoring-contract]+components: []+families: []+deciding_specs: []+---++# Typography hierarchy design specification++## User intent++People should be able to triage a surface quickly because headings, body copy,+labels, code, and supporting text are unmistakably different. Reading should+remain comfortable across dense and editorial theme personalities.++## Design principles++- **DR1 — Type roles communicate purpose.** Text MUST use a role whose hierarchy+ matches its function rather than an arbitrary nearby size.+- **DR2 — Adjacent roles remain distinguishable.** Meaningful hierarchy MUST come+ from visible contrast in size, weight, placement, or a deliberate combination.+- **DR3 — Multi-line text has room to read.** Body and supporting content MUST+ preserve comfortable leading and line measure.+- **DR4 — Theme personality preserves semantics.** Themes MAY tune scale and+ density, but headings, body, labels, and supporting roles MUST retain their+ relative meaning.++## Anatomy and hierarchy++| Role | Purpose | Required relationship |+| ----------------------- | ------------------------------------------ | ----------------------------------------------------------------- |+| display or page heading | Establishes the strongest reading landmark | Clearly outranks section and body content |+| section heading | Organizes content within a surface | Distinct from both page context and body copy |+| body | Carries primary reading content | Optimized for sustained legibility |+| label | Identifies a control or compact datum | Remains associated with its value or control |+| supporting text | Adds secondary context | Quieter but still readable and distinguishable from disabled text |+| code or data text | Preserves technical or tabular structure | Remains legible without borrowing heading emphasis |++## State representation++Loading, disabled, status, selected, and truncated states MUST preserve the text+role's identity. State styling must not flatten heading and body hierarchy or make+supporting text indistinguishable from unavailable content.++## Responsive and input behavior++- **DR5 — Measure remains readable.** Responsive layouts MUST constrain long-form+ text rather than allowing lines to expand without bound.+- **DR6 — Wrapping preserves hierarchy.** Labels and headings MAY wrap, but their+ relationship to controlled or grouped content MUST remain clear.++## Accessibility intent++Text should remain legible at supported zoom levels, modes, and theme settings.+Hierarchy should not rely on color alone, and all-caps or unusual tracking should+not undermine sustained reading.++## Representative examples++- A page title, section heading, body paragraph, and supporting note remain+ distinguishable when viewed quickly and when zoomed.+- A dense dashboard and an editorial surface use different personalities while+ preserving the same semantic role order.++## Visual references++No normative assets are included. Dense, editorial, zoomed, and constrained+examples should be added under `docs/design/assets/typography-hierarchy/` before+promotion.++## Component contract links++No component links are asserted in this seed draft.++## Decision log++No repository design decision has approved this record yet. It distills the+legibility and hierarchy intent from the public Design Conventions wiki without+copying type scales or numeric checks.++## Open questions++- **OQ1 — Scale reconciliation.** The source material's default scale and its+ adjacent-step hierarchy smell use different ratios. The intent and audit check+ need reconciliation before promotion.+- **OQ2 — Reference content.** Which realistic content set should verify every+ role across themes and widths?++## Content boundary++This file defines typographic intent. It does not define font sizes, weights,+line-height values, token names, text component APIs, or audit thresholds.diff --git a/docs/design/user-states.md b/docs/design/user-states.mdnew file mode 100644index 0000000000..dc688b6bf1--- /dev/null+++ b/docs/design/user-states.md@@ -0,0 +1,128 @@+---+schema_version: 1+template_version: 1+kind: design+id: design:user-states+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [ernestt, cixzhang]+review_triggers: [visual, interaction, accessibility]+verified_by: []+architecture: [architecture:interaction-modality, architecture:theme-tokens]+components: []+families: []+deciding_specs: []+---++# User states design specification++## User intent++A person should recognize whether an element is available, hovered, pressed,+focused, or selected without learning a new visual language for every component.+Each family should reuse the smallest suitable set of state representations.++## Design principles++- **DR1 — Minimize representations per intention.** A component MUST reuse an+ established treatment before introducing another visual for the same state.+- **DR2 — Design the complete user-driven interaction cycle.** Every interactive+ component MUST account for rest, hover where available, focus, press or+ activation, and its selected state where relevant. Disabled, loading, and+ status representations belong to `design:system-states`.+- **DR3 — Family consistency comes first.** A component MUST choose the treatment+ that fits its interaction archetype and remain consistent with sibling+ components before pursuing superficial system-wide sameness.+- **DR4 — Selection is one intention with archetype-specific treatments.** A+ selected item MUST remain perceivable, while its visual treatment MAY differ+ for toggles, segments, navigation, cards, and rows.++## Anatomy and hierarchy++| Role | Purpose | Required relationship |+| --------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------- |+| base surface | Establishes the component's resting role | Remains identifiable under every transient state treatment |+| interaction overlay or ring | Signals pointer response | Adds feedback without replacing content or semantic meaning |+| focus indicator | Shows the current keyboard focus owner | Has one clear owner and remains distinct from hover and selection |+| selection indicator | Shows persistent current or chosen state | Fits the component archetype and remains stable after interaction ends |+| content | Carries the component's label, value, or affordance | Remains legible through transient and persistent states |++## State representation++| State | Required representation | Allowed variation |+| -------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |+| rest | Uses base role tokens without transient interaction decoration | Theme controls visual character |+| hovered, surface archetype | A quiet overlay changes the surface while preserving its base | Overlay strength may vary by theme |+| hovered, field archetype | Border or inset treatment makes the field boundary more apparent | Field families may tune the ring treatment |+| pressed | Immediate tactile compression or stronger surface feedback confirms activation | Components that cannot transform may use another established family response |+| focused, action archetype | A clearly separated external indicator identifies the focus owner | Shape follows the focused element |+| focused, field archetype | An emphasized border and inset treatment identify the owning field | Composed fields may paint on an owning wrapper or visual proxy |+| selected, filled | A compact binary control fills to communicate on or chosen | Used for checks, radios, and switches where the control itself carries state |+| selected, surface | The active segment separates from its containing track | Used for segmented choices |+| selected, edge | An edge or underline marks the current destination or step | Used for tabs, entries, and ordered progress |+| selected, border | A selected container receives a clear boundary treatment | Used for selectable cards and similar surfaces |+| selected, depressed | A persistent quiet fill marks the current row or toggle action | Used for navigation rows, list rows, and toggle buttons |+| reordering | Uses the drag and insertion treatment owned by `design:ordered-collection-reordering` | Applies only to ordered collections with a dedicated handle |++## Responsive and input behavior++- **DR5 — Hover remains conditional.** Hover treatment MUST appear only where the+ input can intentionally hover and MUST NOT be required to discover or activate+ the control.+- **DR6 — Focus follows the semantic owner.** Responsive composition MAY move or+ visually proxy a control, but it MUST preserve one perceivable focus indicator+ for the semantic focus owner.+- **DR7 — Persistent state survives reflow.** Selection MUST remain perceivable+ when labels wrap, navigation collapses, or a control changes orientation.++## Accessibility intent++Keyboard users should always be able to identify the current focus owner.+Pointer, touch, and pen users should receive feedback without sticky or+misleading hover. Selection must not be communicated by a subtle color change+alone when shape, edge, fill, or text can provide a durable cue.++Interaction modality mechanics, selectors, ARIA mapping, and component event+behavior are owned by architecture and component contracts.++## Representative examples++- A secondary action moves from rest to hover, press, and keyboard focus without+ changing the meaning or position of its label.+- A field uses its family ring treatment rather than borrowing an action outline.+- Tabs use an edge indicator while a checkbox uses a filled indicator; both+ clearly communicate the same selected intention through their archetypes.++## Visual references++No normative assets are included in this seed draft. Approved examples should be+copied into `docs/design/assets/user-states/` with state, theme,+viewport, demonstrated decision, and alt-text metadata before promotion.++## Component contract links++No component contract links are asserted in this seed draft. Candidate component+and family adoptions should cite individual `DR` requirements after review.++## Decision log++No repository design decision has approved this record yet. It distills the+human-facing state vocabulary from the public Design Conventions wiki while+leaving implementation and component semantics with their current owners.++## Open questions++- **OQ1 — Representative set.** Which components are the canonical examples for+ each hover, focus, and selection archetype?+- **OQ2 — Cross-family exceptions.** Which shipped components intentionally use+ a different state treatment, and should the family or this design record own+ each exception?++## Content boundary++This file defines visual intent for user-driven states. It does not define prop+names, selectors, ARIA attributes, focus-management mechanics, token names,+component behavior, audit results, or consumer guidance.