Skip to content

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

TypeScript

feat(FileInput): add upload icon theme target (#6152)

athz98f9d36759d6
diff --git a/.changeset/file-input-icon-target.md b/.changeset/file-input-icon-target.md
new file mode 100644
index 0000000000..d5c0c7df20
--- /dev/null
+++ b/.changeset/file-input-icon-target.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Expose FileInput's upload icon as a mode-aware theme target (#5417)
+@athz
diff --git a/packages/core/src/FileInput/FileInput.doc.mjs b/packages/core/src/FileInput/FileInput.doc.mjs
index 2d7ce1c18c..c79ce7ab31 100644
--- a/packages/core/src/FileInput/FileInput.doc.mjs
+++ b/packages/core/src/FileInput/FileInput.doc.mjs
@@ -142,6 +142,7 @@ export const docs = {
theming: {
targets: [
{className: 'astryx-file-input', visualProps: ['mode', 'status']},
+ {className: 'astryx-file-input-icon', visualProps: ['mode']},
],
},
usage: {
@@ -270,6 +271,7 @@ export const docsZh = {
theming: {
targets: [
{className: 'astryx-file-input', visualProps: ['mode', 'status']},
+ {className: 'astryx-file-input-icon', visualProps: ['mode']},
],
},
usage: {
diff --git a/packages/core/src/FileInput/FileInput.spec.md b/packages/core/src/FileInput/FileInput.spec.md
new file mode 100644
index 0000000000..1a6bbd4db7
--- /dev/null
+++ b/packages/core/src/FileInput/FileInput.spec.md
@@ -0,0 +1,199 @@
+---
+schema_version: 3
+template_version: 4
+kind: component
+id: component:FileInput
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-14
+owners: [cixzhang, imdreamrunner]
+review_triggers: [theming]
+verified_by:
+ [
+ packages/core/src/FileInput/FileInput.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
+ scripts/check-knowledge.mjs,
+ ]
+modules: []
+families: [family:input-fields]
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# FileInput component contract
+
+## Intent
+
+FileInput presents a labelled file-selection field in compact input or dropzone
+form. This contract records its current consumer anatomy and approves separate theme
+ownership for the upload affordance that FileInput paints through Icon.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive public theming target; no existing target,
+ runtime default, DOM, prop, interaction, or accessibility behavior changes
+- Controlled/uncontrolled behavior: unchanged; FileInput remains controlled
+- Migration decision: `component:FileInput/DEC-1`
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The visible file-selection surface and its input/dropzone mode.
+- Whether, where, and at what default size the upload affordance appears.
+- Reflecting FileInput's mode on its locally owned theme targets.
+
+**Does not own / non-goals**
+
+- The upload artwork or Icon's base color, size, and accessibility semantics —
+ owned by `component:Icon`.
+- Label, description, clear-control, and validation-message presentation — owned
+ by `component:Field` and `component:FieldStatus`.
+- Loading-indicator presentation — owned by `component:Spinner`.
+- A new prop, variant, icon slot, or custom property.
+
+## Public concepts
+
+No consumer prop changes. The `file-input-icon` target gives themes a
+same-element seam for the Upload icon and reflects the existing `mode` axis. The
+existing `file-input` target remains on the visible selection surface and keeps
+its `mode` and `status` axes.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Review state |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------- |
+| FR1 | The visible selection surface carries `file-input` and reflects the existing `mode` and resolved status. | Current source, public docs, and focused tests | Verified current behavior |
+| FR2 | When not loading, input mode renders an upload affordance at the small Icon size. Dropzone mode renders it at the medium Icon size only while no file is selected. | Current source and focused tests | Verified current behavior |
+| FR3 | Icon owns the rendered glyph's base size, color, and accessibility semantics; FileInput owns the affordance's mode-dependent placement and default size. | Current composition and component boundaries | Verified current composition |
+| FR4 | The rendered upload affordance MUST carry `file-input-icon` with the existing `mode` reflected, so a theme can restyle the glyph box without structural selectors or changing every Icon that uses the same artwork. | Owner-approved target contract | Approved additive contract |
+| FR5 | Adding the target MUST NOT change the default artwork, computed layout, interaction, file-selection behavior, accessible name, or decorative Icon semantics. | Compatibility policy and focused regression tests | Required compatibility behavior |
+
+### Allowed variation
+
+- **AV1 — Theme paint.** A theme may change standard visual
+ properties such as the upload glyph's size or color through
+ `file-input-icon`; FileInput still owns whether and where the affordance renders.
+- **AV2 — Artwork.** Icon registry and future icon-slot decisions may change the
+ artwork without changing this CSS target's ownership of the painted glyph box.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ------------------------ | ------------------------------------------------------------------------ | --------------------------------------- |
+| Input, empty or selected | Small upload affordance renders on the input surface when not loading. | Files, placeholder, status, theme paint |
+| Dropzone, empty | Medium upload affordance renders above the placeholder when not loading. | Drag state, placeholder, theme paint |
+| Dropzone, selected | File names replace the upload affordance. | File names and status |
+| Loading | Spinner replaces the upload affordance. | Mode and loading presentation |
+
+### Transformation and precedence order
+
+- **ORD1 — Content selection.** Resolve loading and selected-file state, choose
+ input or dropzone content, then render the mode-sized upload affordance only in
+ the states recorded by FR2.
+- **ORD2 — Theme composition.** Icon applies its base size and color, then the
+ same-element FileInput target participates in the existing theme layer and
+ standard Icon styling merge order.
+
+### Performance and resources
+
+- **PR1 — No new work.** The additive target performs no measurement, listener,
+ observer, state update, or additional render pass.
+
+## Accessibility contract
+
+The upload affordance remains decorative. The existing focusable file-selection
+trigger, label, description, required/invalid state, disabled explanation, and
+selection announcements remain unchanged.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------------------------- | ---------------------------------------- | -------------- | ------------------ |
+| Drop zone | Presents the visible file-selection surface in input or dropzone form. | Current source and public docs | Prominent | FR1 |
+| Upload icon | Hints at the upload action and changes default size with the selected mode. | Current source and owner-approved target | Supporting | FR2, FR3, FR4 |
+| Shared feedback | Uses Field, FieldStatus, and Spinner for labels, validation, and loading treatment. | Current shared composition | Supporting | FR5 |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Label": {
+ "delegatesTo": {"owner": "component:Field", "target": "field-label"}
+ },
+ "Description": {
+ "none": {
+ "reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"
+ }
+ },
+ "Drop zone": {"target": "file-input"},
+ "Upload icon": {"target": "file-input-icon"},
+ "Placeholder": {"inherits": "file-input"},
+ "File name display": {"inherits": "file-input"},
+ "Clear button": {
+ "delegatesTo": {
+ "owner": "component:Field",
+ "target": "input-clear-button"
+ }
+ },
+ "Spinner": {
+ "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
+ },
+ "Status message": {
+ "delegatesTo": {
+ "owner": "component:FieldStatus",
+ "target": "field-status"
+ }
+ }
+}
+```
+
+The `file-input-icon` disposition records the approved target state. Icon still
+owns the general `icon` target and base glyph semantics; FileInput's narrower
+target owns only this stable upload position and its existing mode distinction.
+
+## Family and system relationships
+
+- `family:input-fields` owns shared labelled-field and validation behavior.
+- `architecture:component-theming-surface` owns target qualification, anatomy
+ mapping, and the requirement that public targets sit on stable painted parts.
+- Field, FieldStatus, Icon, and Spinner retain their existing public target
+ contracts when composed by FileInput.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ----------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------- |
+| FR1, FR2 | `FileInput.test.tsx` rendering and target suites | Input/dropzone; empty/selected/loading | Moving the root target or changing when/at what size the affordance renders breaks focused assertions. | `audit:FileInput/theming` |
+| FR3, FR4, FR5 | `FileInput.test.tsx`, `themingTargets.test.ts`, probe-theme check | Both modes and same-element Icon target | Missing the target, reflecting the wrong mode, or moving it off the glyph fails source/docs/probe coverage. | `audit:FileInput/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Nine anatomy entries and two locally owned targets | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation. | `audit:FileInput/anatomy` |
+
+## Decision log
+
+### DEC-1 — Upload icon is stable FileInput theme anatomy
+
+**Reference:** `component:FileInput/DEC-1`
+**Decider:** cixzhang, 2026-09-14
+
+The upload icon is a stable, consumer-recognizable FileInput affordance whose
+mode-dependent placement and default size belong to FileInput. It receives the
+`file-input-icon` target on the same Icon element that paints the glyph, while
+Icon retains its general target and base glyph semantics.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, implementation
+steps, or shared-component contracts. It links to their owners.
diff --git a/packages/core/src/FileInput/FileInput.test.tsx b/packages/core/src/FileInput/FileInput.test.tsx
index f57a0b8ea9..a615881282 100644
--- a/packages/core/src/FileInput/FileInput.test.tsx
+++ b/packages/core/src/FileInput/FileInput.test.tsx
@@ -119,6 +119,20 @@ describe('FileInput', () => {
expect(screen.getByText('Drop here')).toBeInTheDocument();
});
+ it.each([
+ {mode: 'input' as const, size: 'sm'},
+ {mode: 'dropzone' as const, size: 'md'},
+ ])('exposes the upload icon as a $mode theme target', ({mode, size}) => {
+ render(
+ <FileInput label="Upload" mode={mode} value={null} onChange={() => {}} />,
+ );
+
+ const icon = document.querySelector('.astryx-file-input-icon');
+ expect(icon).toHaveClass('astryx-icon');
+ expect(icon).toHaveAttribute('data-mode', mode);
+ expect(icon).toHaveAttribute('data-size', size);
+ });
+
it('displays selected file name', () => {
const file = createFile('report.pdf', 1024, 'application/pdf');
render(<FileInput label="Document" value={file} onChange={() => {}} />);
diff --git a/packages/core/src/FileInput/FileInput.tsx b/packages/core/src/FileInput/FileInput.tsx
index 35c66d4760..8b4be7fa22 100644
--- a/packages/core/src/FileInput/FileInput.tsx
+++ b/packages/core/src/FileInput/FileInput.tsx
@@ -5,7 +5,7 @@
/**
* @file FileInput.tsx
* @input Uses React, useId, Field, Icon, Spinner, VisuallyHidden
- * @output Exports FileInput component, FileInputProps, FileInputStatus
+ * @output Exports FileInput component, public types, and its root/icon theme targets
* @position Core implementation; consumed by index.ts, tested by FileInput.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
@@ -707,7 +707,12 @@ export function FileInput({
}
return (
<>
- <Icon icon="arrowUp" size="md" color="secondary" />
+ <Icon
+ icon="arrowUp"
+ size="md"
+ color="secondary"
+ {...themeProps('file-input-icon', {mode})}
+ />
<span {...stylex.props(styles.placeholderText)}>
{isDragOver ? t('@astryx.fileInput.dropHint') : displayPlaceholder}
</span>
@@ -728,7 +733,12 @@ export function FileInput({
}
return (
<>
- <Icon icon="arrowUp" size="sm" color="secondary" />
+ <Icon
+ icon="arrowUp"
+ size="sm"
+ color="secondary"
+ {...themeProps('file-input-icon', {mode})}
+ />
<span
{...stylex.props(
hasFiles ? styles.fileNameText : styles.placeholderText,
diff --git a/packages/themes/probe/src/probeTheme.ts b/packages/themes/probe/src/probeTheme.ts
index 1fb9f2cdf6..35c99806d4 100644
--- a/packages/themes/probe/src/probeTheme.ts
+++ b/packages/themes/probe/src/probeTheme.ts
@@ -6,7 +6,7 @@
// test fixture. Regenerate with: pnpm visual:probe-theme
//
// defineTheme takes six things and this covers all six:
-// components 284 targets, 917 selectors (generated from the docs)
+// components 285 targets, 920 selectors (generated from the docs)
// tokens custom properties, read back off the themed element
// icons every registry entry swapped for a marked glyph
// indicators check / radio / checkbox swapped — the swap that reaches furthest
@@ -2356,6 +2356,26 @@ export const probeTheme = defineTheme({
outlineColor: 'hsl(67.1 74% 25%)',
},
},
+ 'file-input-icon': {
+ base: {
+ backgroundColor: 'hsl(351.5 72% 64%)',
+ color: 'hsl(171.1 72% 12%)',
+ borderColor: 'hsl(261.4 81% 25%)',
+ outlineColor: 'hsl(189.9 94% 25%)',
+ },
+ 'mode:input': {
+ backgroundColor: 'hsl(133.7 72% 60%)',
+ color: 'hsl(143.1 87% 12%)',
+ borderColor: 'hsl(309.2 92% 25%)',
+ outlineColor: 'hsl(230.1 94% 25%)',
+ },
+ 'mode:dropzone': {
+ backgroundColor: 'hsl(118.3 93% 60%)',
+ color: 'hsl(269.0 87% 12%)',
+ borderColor: 'hsl(274.5 79% 25%)',
+ outlineColor: 'hsl(236.1 70% 25%)',
+ },
+ },
'form-layout': {
base: {
backgroundColor: 'hsl(189.0 82% 49%)',