Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): define component-owned upload and send icons (#6153)

athz8c8f9a294a0d
diff --git a/docs/specs/AST-032/spec.md b/docs/specs/AST-032/spec.md
new file mode 100644
index 0000000000..b827c1982a
--- /dev/null
+++ b/docs/specs/AST-032/spec.md
@@ -0,0 +1,121 @@
+---
+schema_version: 1
+template_version: 1
+kind: system-spec
+id: spec:AST-032
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-22
+phase: accepted
+owners: [cixzhang, imdreamrunner]
+affects_architecture: [architecture:icon-resolution-and-component-slots]
+affects_families: []
+affects_contributing: []
+affects_consumer_docs: [FileInput, ChatSendButton]
+---
+
+# Component-owned upload and send icon slots
+
+## 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.
+
+## Non-goals
+
+- Adding `upload` or `send` to the shared `IconName` registry.
+- 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.
+
+## 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.
+- **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.
+
+### 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.
+
+## Current-state impact
+
+Current `main` uses the shared `arrowUp` name directly for both component 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` |
+
+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`.
+
+## 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. |
+
+## Decision log
+
+### DEC-1 — Theme component roles before expanding shared icon names
+
+**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.
+
+## Open questions
+
+None.