docs(design): seed design convention records

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.

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.

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.

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.