An open source design system that's fully customizable and agent ready
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 - Dropzone status placement (FR6): the docs mark
attachedunsupported in dropzone mode, and the releasedattachedrendering stays until the next minor release
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:Fieldandcomponent: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 |
| FR6 | Dropzone mode does not offer attached status placement: its tall, custom surface cannot meet the attached conditions of family:input-fields FR8, so under AV6 it offers detached and tooltip. Dropzone resolves attached to detached and defaults to detached from the next minor release; until then the released attached rendering is kept. Input mode keeps attached as its default. |
family:input-fields FR8, AV6, and its status placement conformance note |
Approved; rendering change at the next minor |
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
{
"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-fieldsowns shared labelled-field and validation behavior.architecture:component-theming-surfaceowns 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 |
| FR6 | FileInput.doc.mjs statusVariant entry and the prop's JSDoc in FileInput.tsx |
Dropzone and input modes | A doc or JSDoc that offers attached in dropzone mode, or drops it from input mode, fails review. |
— |
| 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.