An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): make upload a shared icon (AST-032) (#6971)
Cindy Zhang24fe2cdf3be9
diff --git a/docs/specs/AST-032/spec.md b/docs/specs/AST-032/spec.mdindex a41300fbb0..90f6bc1be7 100644--- a/docs/specs/AST-032/spec.md+++ b/docs/specs/AST-032/spec.md@@ -13,108 +13,156 @@ owners: [cixzhang, imdreamrunner]affects_architecture: [architecture:icon-resolution-and-component-slots]affects_families: []affects_contributing: []-affects_consumer_docs: [FileInput, ChatSendButton]+affects_consumer_docs: [FileInput, ChatSendButton, Icon]----# Component-owned upload and send icon slots+# Upload and send icon theming## Intent-Let themes choose the artwork used by FileInput's upload affordance and-ChatSendButton's send action independently, without widening the shared icon-vocabulary or changing either component's default appearance.+Let themes choose the artwork for FileInput's upload affordance and+ChatSendButton's send action without repainting any other icon. Upload is a+shared semantic icon: any surface that uploads can render it, and each theme+draws it in its own style. Send is a ChatSendButton role that a theme maps to a+shared icon.## Non-goals-- Adding `upload` or `send` to the shared `IconName` registry.+- Adding a shared `send` name.- Changing the meaning or artwork of the shared `arrowUp` icon.- Changing FileInput or ChatSendButton interaction, layout, sizing, oraccessibility.- Removing or changing ChatSendButton's existing `sendIcon` prop.- Changing ChatSendButton's stop-state icon.- Prescribing a particular upload, send, or directional drawing.+- Choosing which other components render `upload`; each component's own+ contract decides that.## Requirements-- **FR1 — Upload is a FileInput role.** `ComponentIconSlotMap` MUST include- `file-input-upload`. FileInput's upload affordance MUST resolve that slot with- `arrowUp` as its fallback.+- **FR1 — Upload is a shared icon.** `IconName` MUST include `upload`, the+ shared meaning for sending files or content from the person's device.+ FileInput's upload affordance MUST render `upload` in both input and dropzone+ modes.- **FR2 — Send is a ChatSendButton role.** `ComponentIconSlotMap` MUST include`chat-send-button-send`. ChatSendButton's send state MUST resolve that slotwith `arrowUp` as its fallback.- **FR3 — Existing instance configuration keeps precedence.** An explicit`ChatSendButton.sendIcon` MUST continue to win over the active theme's- component-slot mapping. FileInput gains no new instance prop in this change.-- **FR4 — Themes configure roles, not global meanings.** A theme MAY map each- component slot independently to an existing shared `IconName` or to `null`- through `componentIcons`. This change MUST NOT add `upload`, `send`, or another- component-specific synonym to `IconName`.-- **FR5 — Defaults preserve every shipped surface.** With no component-slot- mapping, both components MUST render the same `arrowUp` artwork, size,- placement, and accessible behavior they render today. Sortable Table and every- other `arrowUp` consumer MUST remain unchanged.-- **IR1 — Owner surfaces stay synchronized.** The public component-slot map,- FileInput and ChatSendButton source, their component documentation and current- contracts, and focused resolver/component tests MUST change together in the- implementation.+ component-slot mapping. FileInput exposes no instance prop for its upload icon.+- **FR4 — Themes draw upload and map send independently.** A theme MAY draw+ `upload` through its `icons` map, as it draws any shared name, and MAY map+ `chat-send-button-send` to an existing shared `IconName` or to `null` through+ `componentIcons`. Drawing `upload` MUST NOT change `arrowUp` or any other+ shared name, and mapping the send slot MUST NOT change `upload`.+- **FR5 — Defaults keep geometry and accessibility.** With no theme artwork for+ `upload`, FileInput MUST render the default `upload` artwork with its existing+ size, placement, color, and accessible behavior. That default MUST depict+ uploading and MUST be distinguishable from `arrowUp`. With no slot mapping and+ no `sendIcon`, ChatSendButton MUST render `arrowUp` with its existing size,+ placement, and accessible behavior. Sortable Table and every other `arrowUp`+ consumer MUST remain unchanged.+- **FR6 — Every shipped registry draws upload.** The default registry, each+ bundled theme, and each CLI theme template MUST supply `upload` artwork in+ that registry's own style. The public `IconRegistry` type describes a complete+ registry and MUST require `upload` like every other shared name, starting in+ the next minor scheduled under `spec:AST-017/FR47`. Until that minor,+ `IconRegistry` MUST accept a complete registry that omits `upload`, and the+ omitted entry resolves the default artwork. A consumer migrates by adding an+ `upload` entry drawn in its registry's style.+- **IR1 — Owner surfaces stay synchronized.** For upload: `IconName`, the+ default registry, every bundled theme and CLI theme template, the documented+ lists of shared icon names, FileInput source and docs, and focused registry+ and FileInput tests MUST change together. For send: the public+ component-slot map, ChatSendButton source, its component documentation and+ current contract, and focused resolver and component tests MUST change+ together.### Platform support-- Supported feature/engine floor: unchanged from the current component-icon- resolver.-- Unsupported behavior: unchanged; themes that omit these slots use each- component's fallback.-- Browser evidence: not required for the default because the rendered artwork- and geometry do not change. Resolver and rendered-component tests cover slot- precedence and fallback; existing visual gates protect the unchanged default.+- Supported feature/engine floor: unchanged from the current icon resolver.+- Unsupported behavior: unchanged; a theme without `upload` artwork or a send+ slot mapping uses the default artwork or the component fallback.+- Browser evidence: FileInput's default glyph changes, so real-browser visual+ evidence MUST show both FileInput modes rendering the upload artwork with+ unchanged geometry in the shipped themes. ChatSendButton's default needs none+ because its artwork and geometry do not change; resolver and component tests+ cover slot precedence and fallback.## Current-state impact-Current `main` uses the shared `arrowUp` name directly for both component roles:+Current `main` renders the shared `arrowUp` icon directly for both roles:-| Owner | Existing instance override | Proposed theme slot | Fallback |-| --------------------------- | -------------------------- | ----------------------- | --------- |-| FileInput upload affordance | none | `file-input-upload` | `arrowUp` |-| ChatSendButton send state | `sendIcon` | `chat-send-button-send` | `arrowUp` |+| Owner | Instance override | Theme control | Default |+| --------------------------- | ----------------- | ---------------------------- | ------------------------ |+| FileInput upload affordance | none | `icons.upload` | default `upload` artwork |+| ChatSendButton send state | `sendIcon` | `chat-send-button-send` slot | `arrowUp` |-Each meaning currently belongs to one component and has no demonstrated-cross-component shared-name contract. The current icon architecture therefore-routes both through component-owned slots. If a reusable upload or send meaning-later meets the separate shared-icon admission bar, a future decision may add a-shared name and change a slot's fallback or recommended mapping through the-normal compatibility process.--The before-to-after behavior is: each component currently reads `arrowUp`-directly; each will instead resolve its own stable role, while an omitted theme-mapping still resolves to `arrowUp`.+FileInput's default glyph changes from a directional arrow to the upload+artwork; its size, placement, color, and accessible behavior stay the same.+FileInput stops following a theme's `arrowUp` artwork: a theme restyles it+through `upload`, and a theme without `upload` artwork shows the default upload+artwork there. ChatSendButton keeps its default artwork and resolves its own+slot once that slot is implemented. Every Astryx-shipped registry gains an+`upload` entry, and consumer registries keep compiling until the minor that+requires `upload` (FR6).## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| -------- | ------------------------------------------------------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------- |-| FR1–FR2 | component-slot type and resolver tests; rendered component tests | default theme, mapped name, explicit `null` | A missing or misspelled slot, direct `arrowUp` lookup, or ignored mapping fails. |-| FR3 | ChatSendButton precedence tests | explicit `sendIcon`, theme mapping, fallback | A theme overrides caller content or caller content stops replacing the default fails. |-| FR4 | Icon public-type tests and theme normalization tests | two independent component mappings | Adding shared names or coupling the two role mappings fails the contract. |-| FR5 | existing FileInput, ChatSendButton, Table, and visual evidence | unthemed and shipped themes; send/upload/sort | Default artwork, geometry, accessible output, or unrelated `arrowUp` use changes. |-| IR1 | `pnpm check:knowledge`, focused docs/source consistency assertions | component docs, current contracts, public types | A stale owner surface or undocumented slot blocks the implementation. |+| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | Icon public-type and registry tests; rendered FileInput tests | default registry, theme `icons.upload`, input and dropzone modes | `upload` missing from `IconName`, FileInput reading another name, or theme `upload` artwork not reaching FileInput fails. |+| FR2–FR3 | component-slot type and resolver tests; rendered ChatSendButton precedence tests | default theme, mapped name, explicit `null`, explicit `sendIcon` | A missing or misspelled slot, direct `arrowUp` lookup, ignored mapping, or a theme overriding caller content fails. |+| FR4 | registry resolution tests with independent theme overrides | theme drawing only `upload`; theme mapping only the send slot | Theme `upload` artwork that changes `arrowUp` or another name, or a send mapping that changes `upload`, fails. |+| FR5 | focused FileInput and ChatSendButton tests; existing Table tests; real-browser visual evidence | unthemed and shipped themes; light and dark; input, dropzone, send, and sort | Changed geometry or accessible output, an `upload` default identical to `arrowUp`, or any changed `arrowUp` consumer fails. |+| FR6 | public-type tests; registry completeness tests over the default registry, bundled themes, and CLI theme templates; theme fallback test | complete registry with and without `upload`; theme without `upload` artwork | A shipped registry without `upload`, a complete registry that stops compiling before the minor, or an omitted `upload` that renders nothing fails. |+| IR1 | `pnpm check:knowledge`, focused docs/source consistency assertions | shared icon-name lists, component docs, current contracts, public types | A stale owner surface or an undocumented shared name blocks the implementation. |## Decision log-### DEC-1 — Theme component roles before expanding shared icon names+### DEC-1 — Send is a ChatSendButton role**Reference:** `spec:AST-032/DEC-1`-**Decider:** `cixzhang`, `2026-09-22`--FileInput upload and ChatSendButton send are component-owned roles. They receive-`file-input-upload` and `chat-send-button-send` slots under the current component-icon architecture, with `arrowUp` as the compatibility fallback. The existing-ChatSendButton instance prop remains the highest-precedence choice.--Rejected for this change: adding global `upload` and `send` names. Each proposed-name currently serves one owning component, so the evidence does not establish a-reusable shared vocabulary entry. Also rejected: continuing to read `arrowUp`-directly, because that leaves themes unable to choose these component roles-independently.+**Decider:** `cixzhang`, `2026-09-22`; amended `2026-10-05`++ChatSendButton's send action is a component-owned role. It receives the+`chat-send-button-send` slot under the current component icon architecture,+with `arrowUp` as the compatibility fallback, and the existing `sendIcon` prop+remains the highest-precedence choice.++Rejected: continuing to read `arrowUp` directly, because themes could not then+choose the send icon without repainting every `arrowUp`.++### DEC-2 — Upload is a shared icon++**Reference:** `spec:AST-032/DEC-2`+**Decider:** `cixzhang`, `2026-10-05`++Uploading is a general action with a conventional glyph distinct from+directional arrows. As a shared name, `upload` is drawn once per theme in that+theme's style, and every surface that uploads renders the same theme-drawn+glyph. A shared name is permanent public vocabulary, so one is added on the+owner's design direction rather than on a count of current consumers. `upload`+meets that bar: designers need to draw a real upload glyph, and no existing+shared name can carry it.++Rejected: a `file-input-upload` component slot, because a slot maps only to an+existing shared name and so cannot give upload artwork of its own.++### DEC-3 — Complete registries require upload from the next minor++**Reference:** `spec:AST-032/DEC-3`+**Decider:** `cixzhang`, `2026-10-05`++A complete registry lists every shared name, so `IconRegistry` requires+`upload` like the rest: a complete theme registry that type-checks draws upload+in its own style instead of silently borrowing the default artwork. Requiring a+key breaks released complete registries, so the requirement takes effect in a+scheduled minor (`spec:AST-017/FR1`, `FR47`, `FR48`); until then `upload` is+the one key a complete registry may omit.++Rejected: a permanently optional `upload`, because it would be the only shared+name a complete registry could leave out.## Open questions