Skip to content

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.md
index 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, or
accessibility.
- 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 slot
with `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