From 207fff61c7b16fa3ea4143bca19b01311f3a163f Mon Sep 17 00:00:00 2001 From: Ernest Tien Date: Mon, 31 Aug 2026 17:28:04 -0700 Subject: [PATCH] docs(design): seed design convention records --- docs/design/README.md | 30 +++++ docs/design/agentic-states.md | 115 ++++++++++++++++ docs/design/color-emphasis.md | 110 +++++++++++++++ docs/design/control-rhythm.md | 98 ++++++++++++++ docs/design/elevation-hierarchy.md | 101 ++++++++++++++ docs/design/motion.md | 102 ++++++++++++++ docs/design/ordered-collection-reordering.md | 132 ++++++++++++++++++ docs/design/shape-relationships.md | 97 ++++++++++++++ docs/design/spatial-hierarchy.md | 99 ++++++++++++++ docs/design/system-states.md | 124 +++++++++++++++++ docs/design/template-composition.md | 133 +++++++++++++++++++ docs/design/typography-hierarchy.md | 104 +++++++++++++++ docs/design/user-states.md | 128 ++++++++++++++++++ 13 files changed, 1373 insertions(+) create mode 100644 docs/design/agentic-states.md create mode 100644 docs/design/color-emphasis.md create mode 100644 docs/design/control-rhythm.md create mode 100644 docs/design/elevation-hierarchy.md create mode 100644 docs/design/motion.md create mode 100644 docs/design/ordered-collection-reordering.md create mode 100644 docs/design/shape-relationships.md create mode 100644 docs/design/spatial-hierarchy.md create mode 100644 docs/design/system-states.md create mode 100644 docs/design/template-composition.md create mode 100644 docs/design/typography-hierarchy.md create mode 100644 docs/design/user-states.md diff --git a/docs/design/README.md b/docs/design/README.md index cdfdef66f8af3..0885614889f39 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, current audit results, or consumer usage guidance. Component and family contracts link to stable design requirement IDs instead of copying their rationale. diff --git a/docs/design/agentic-states.md b/docs/design/agentic-states.md new file mode 100644 index 0000000000000..e0b1f901382de --- /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.md new file mode 100644 index 0000000000000..965ee31eb7f2c --- /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.md new file mode 100644 index 0000000000000..5c0f674f679e8 --- /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.md new file mode 100644 index 0000000000000..700de1049c3c8 --- /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.md new file mode 100644 index 0000000000000..fc50424d2777c --- /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.md new file mode 100644 index 0000000000000..75bf4129c658f --- /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.md new file mode 100644 index 0000000000000..2dd8e134a1d2f --- /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.md new file mode 100644 index 0000000000000..469a10cb7fa42 --- /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.md new file mode 100644 index 0000000000000..e6be1ea8ba5a7 --- /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.md new file mode 100644 index 0000000000000..f4daead44ff7e --- /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.md new file mode 100644 index 0000000000000..df6275a5bd8fe --- /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.md new file mode 100644 index 0000000000000..dc688b6bf1490 --- /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.