@d4gger/design-system 3.0.1 → 4.0.1

package/dist/docs/components/environment-ribbon.md

@@ -0,0 +1,126 @@
+---
+title: EnvironmentRibbon
+status: canonical
+category: Components
+archetype: primitive
+depends_on:
+  - "@radix-ui/react-slot (powers `asChild`)"
+---
+
+# EnvironmentRibbon
+
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+
+## Purpose
+
+A floating warning pill that says the app is not running in production, with a warm haze behind the top edge so the warning reads on
+every page without taking layout. It is a static label: no close control, no action, no environment logic. The app decides when to
+render it (off production only) and passes the label (for example "Staging environment"); the component is only the surface.
+
+It is **not** a `Banner` (a hero mass: label, headline value), an `Alert` (an in-flow message with actions) or a `Badge` (an inline chip
+that cannot float or carry a haze). One fixed hue, the `warning` ramp, for every environment: the label tells STAGE from DEV.
+
+Wild references (decisions in `docs/feature/design-system/environment-ribbon/decisions.md`): `django-admin-env-notice` (a label and colour per
+environment, fixed to the top or floating), `wp-environment-ribbon` (a slim ribbon on every admin screen, hidden in production), the GOV.UK
+phase banner (a tag and a sentence on every page of a service).
+
+## Anatomy & slots
+
+**Parent:** `EnvironmentRibbon`, a flat export with no slots. It renders two siblings: an optional decorative haze, then the pill.
+
+| Part | Element | Renders | Notes |
+|---|---|---|---|
+| pill | `<div role="status">` (or `Slot` child when `asChild`) | `dsx-environment-ribbon` + `data-slot="environment-ribbon"` + `data-placement` | The label is its children; put an `Icon` inside for a glyph. |
+| haze | `<span aria-hidden="true">` | `dsx-environment-ribbon__haze` + `data-slot="environment-ribbon-haze"` + `data-placement` | Decorative; omitted with `haze={false}`. Not a public slot. |
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `placement` | `'fixed' \| 'contained'` | `'fixed'` | no | `fixed` pins the pill to the viewport top and the haze to the viewport; `contained` positions both absolutely inside the nearest positioned ancestor (demos, framed compositions). | no |
+| `haze` | `boolean` | `true` | no | Draws the warm haze behind the top edge. `false` draws the pill alone. | no |
+| `asChild` | `boolean` | `false` | no | Renders the pill through `Slot`; the consumer supplies the host element. | no |
+| `role` | `string` | `'status'` | no | Native attribute; override only with a reason. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-environment-ribbon`. | no |
+
+Rules:
+
+- Children are the label: one short line. A label wider than the room truncates with an ellipsis; shorten the label rather than expect a wrap.
+- The component knows no environment. The app renders it only when the environment is not production.
+- The haze needs an isolated ancestor (`isolation: isolate`, as `.dsx-brand-ambient` is). It paints behind in-flow content and glass panels, over
+  that ancestor's background. Without an isolated ancestor the haze can fall behind an opaque wrapper background and not show.
+- Render it once per frame, not per page.
+
+## CSS class contract
+
+**Root class:** `dsx-environment-ribbon`
+
+| Attribute | Allowed values | Hook | CSS file |
+|---|---|---|---|
+| `data-placement` | `fixed`, `contained` | `.dsx-environment-ribbon:where([data-placement='contained'])` and the haze's twin switch to absolute positioning | `environment-ribbon.css` |
+| `data-slot` | `environment-ribbon`, `environment-ribbon-haze` | hooks | `environment-ribbon.css` |
+
+**Classes:** `dsx-environment-ribbon`, `dsx-environment-ribbon__haze`.
+
+No `data-variant`, `data-size`, `data-accent-color`, `data-radius` or `data-high-contrast` is written (contract profile: none).
+
+**Responsive behavior:** none in CSS. On a phone the frame reserves the row the pill occupies; the component writes no breakpoints.
+
+**Reduced motion:** not applicable; the ribbon has no motion.
+
+## Token mapping
+
+| Property | Token | Role |
+|---|---|---|
+| Position (fixed) | `inset-block-start: var(--dsx-space-sm)`; `inset-inline: var(--dsx-space-3)`, `margin-inline: auto`, `inline-size: fit-content` | centred with logical properties, so it holds in right-to-left |
+| Width cap | `max-inline-size: calc(100% - 2 * var(--dsx-space-3))` | the containing block less the two gutters; without it `nowrap` makes the pill refuse to shrink (min-content equals max-content), so a long label would spill instead of truncating |
+| Stacking | `var(--dsx-z-index-fixed)` | above sticky chrome, below overlays and modals |
+| Surface | `var(--dsx-color-warning-container)` | the `Badge` warning recipe, the look passed in the vision |
+| Ink | `var(--dsx-color-on-warning-container)` | paired ink |
+| Border | `var(--dsx-border-width-sm) solid var(--dsx-color-warning)` | keeps the edge over the haze; survives forced-colors |
+| Shadow | `var(--dsx-panel-shadow)` | floating elevation |
+| Radius | `var(--dsx-rounded-full)` | pill |
+| Padding | `var(--dsx-space-xs)` block, `var(--dsx-space-sm)` inline | as `Badge` |
+| Min height | `var(--dsx-size-md)` | as `Badge` size md |
+| Type | `var(--dsx-typography-label-small-*)` | compact label |
+| Haze colour | `color-mix(in srgb, var(--dsx-color-warning) calc(var(--dsx-effect-ambient-strength) * <multiple>), transparent)` | a multiple (3.2, written inline in the rule, as Sidebar's ambient wash does) of the theme-aware accent-haze strength: 32% in dark, about 51% in light. Tuned in the browser and kept (batch `decisions.md` D-10); stronger than the accent haze's primary wash (2.2) on purpose, since a warning has to read on every page |
+| Haze stacking | `z-index: -1` | behind panels and in-flow content, over the isolated ancestor's background |
+
+The haze geometry is a radial gradient in rem, anchored at the top centre and fading to transparent; no raw colour.
+
+Rules: no raw colour, spacing, radius or motion values in `environment-ribbon.css`.
+
+## Accessibility
+
+- The pill is `role="status"`: advisory information, not an alert (MDN, `status` role). It is a polite live region by definition. The
+  component does not rely on a screen reader announcing it when it appears (MDN does not say whether static content at load is announced);
+  its text is the region's content, in the reading order. The `status` role takes no accessible name from content and needs none; a consumer
+  who wants a name passes `aria-label`. Verification reads the browser's accessibility tree.
+- Never focusable and never takes focus. Not dismissible (PASSPORT R-13: it must read as a warning on every page).
+- The meaning is in the words, not the colour: the label says which environment. The haze is `aria-hidden` and decorative.
+- Contrast: the pill uses the container pair that `Badge variant="warning"` uses (`qa:contrast` covers the pair); the haze carries no text.
+- Forced colors: the hairline border keeps the pill's edge when fills are replaced.
+
+## Playground demo spec
+
+**Default story:** a framed, isolated box with a `contained` ribbon reading "Staging environment", haze on.
+**Variant stories:** `haze={false}` (the pill alone) beside the default; `placement="contained"` is the demo default (`fixed` pins to the playground
+viewport and is documented only).
+**State stories:** a long label in a 320px frame (truncation, no overflow).
+**Composition story:** the ribbon over a glass panel inside a `dsx-brand-ambient` wrapper, showing the layering (haze behind the panel's blur, pill on top).
+**Token story:** inside `Theme` with each of the five accents (the warning hue does not change; the accent haze beside it does).
+**A11y story:** `EnvironmentRibbon.test.tsx` runs `vitest-axe`.
+
+| Prop | Control | Default |
+|---|---|---|
+| `placement` | select | `contained` (demo) |
+| `haze` | boolean | `true` |
+
+## Wiring notes
+
+**Composes from:** `@radix-ui/react-slot`.
+
+**State boundaries:** owned by `EnvironmentRibbon`: nothing persistent. Owned by the consumer: whether to render it (not in production), the label and its
+translation, the room the pill takes at phone widths, and the isolated ancestor the haze needs.
+
+**Used by (planned):** the `frontend-admin` shell frame (`frontend/admin/shell`), once per frame, only when the admin context's environment is STAGE or DEV.

package/dist/docs/components/field.md

@@ -92,6 +92,7 @@ Rules:
 **Responsive behavior:**
 
 - The `responsive` orientation uses `grid-template-columns: repeat(auto-fit, minmax(var(--dsx-size-popover-min-width), 1fr))`. The CSS does not write `@media` rules directly. None of the prop defs are `responsive: true`.
+- The `vertical` orientation, the control region (`Field.Content`), `Field.Group` and `Field.Set` have one column, `minmax(0, 1fr)`, so a control with a wide intrinsic width (a password input at about 300px) shrinks with a narrow container instead of widening the row past it (G-22, `docs/feature/design-system/field-narrow-track/`).
 
 **Reduced motion:**
 
@@ -105,6 +106,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 |---|---|---|
 | Row gap | `var(--dsx-space-xs)` | Default row gap. |
 | Row min-width | `0` | Allows the grid to shrink. |
+| Column (vertical orientation, control region, group, fieldset) | `minmax(0, 1fr)` | One column that fills the container and never asks for more. Without it the implicit `auto` track is sized from the controls' min-content (a native input is about 20 characters wide), so a field spilled past a narrow card. |
 | Horizontal label column | `minmax(var(--dsx-size-field-label-min), var(--dsx-size-field-label-max))` | Label column size for `horizontal` orientation. |
 | Horizontal label alignment | `end` | Label text magnetizes toward the control in `horizontal` orientation. |
 | Horizontal row column gap | `var(--dsx-space-md)` | Row gap for `horizontal` orientation. |

package/dist/docs/components/file-upload.md

@@ -41,7 +41,7 @@ A card-based file selection surface with a dropzone, a list of file rows, and a
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Card-level size token. Drives `data-size`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Card-level size; `sm` uses a wrapping inline attachment layout, `md`/`lg` use a centered drop area. Drives `data-size`. | no |
 | `asChild` | `boolean` | `false` | no | Renders the card through `Slot` from `@radix-ui/react-slot`. | no |
 | Standard `Card` props | `CardProps` | n/a | no | The root extends `CardProps`, so variant, radius, and standard card attributes pass through. | no |
 | `children` | `React.ReactNode` | `undefined` | no | `FileUpload.Dropzone`, `FileUpload.List`, and `FileUpload.Item` children. | no |
@@ -109,7 +109,7 @@ Rules:
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-size` | `sm`, `md`, `lg` | n/a (no size-specific root CSS today) | `file-upload.css` |
+| `data-size` | `sm`, `md`, `lg` | Root controls dropzone layout, minimum height and padding | `file-upload.css` |
 | `data-dragging` | `true` | `.dsx-file-upload__dropzone[data-dragging='true']` thicker accent dashed border + active background (no ring) | `file-upload.css` |
 | `data-status-tone` | `danger` (omitted when `muted`) | `.dsx-file-upload__item:where([data-status-tone='danger']) .dsx-file-upload__status` error color | `file-upload.css` |
 
@@ -135,6 +135,8 @@ Rules:
 **Responsive behavior:**
 
 - The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size is single-value only.
+- The `sm` dropzone places illustration, text and action in a wrapping row. Consumers choose this attachment composition for narrow forms; `md`/`lg` retain the centered drag area. All sizes grow with content and localized labels.
+- FileUpload owns its dropzone minimum height and typography; it does not inherit EmptyState's standalone empty-page minimum height.
 
 **Reduced motion:**
 
@@ -148,7 +150,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 |---|---|---|
 | Root layout | `display: grid; gap: var(--dsx-space-md); width: 100%` | Surface layout. |
 | Dropzone width | `width: 100%` | Full width. |
-| Dropzone min-height | `calc(var(--dsx-size-4xl) * 2)` | Tall enough to invite a drop. |
+| Dropzone min-height | `var(--dsx-size-4xl)` / `calc(var(--dsx-size-4xl) * 2)` / `calc(var(--dsx-size-4xl) * 2.5)` | sm/md/lg content-growing minimums. |
+| Dropzone padding / gap | `var(--dsx-space-sm)` / `var(--dsx-space-md)` / `var(--dsx-space-lg)`; gap `var(--dsx-space-sm)` | sm/md/lg padding and compact internal spacing. |
+| Dropzone illustration | `var(--dsx-size-lg)` square | Upload affordance rather than an empty-page illustration. |
+| Dropzone title | `var(--dsx-typography-label-large-*)` | Form-level title, independent of EmptyState headline typography. |
 | Dropzone border | `var(--dsx-border-width-md)` dashed `var(--dsx-color-outline)` | Resting edge, visible against the sunken fill. |
 | Dropzone radius | `var(--dsx-rounded-lg)` | Round corners. |
 | Dropzone background | `var(--dsx-color-surface-sunken)` | Sunken surface. |
@@ -160,9 +165,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Item icon size | `var(--dsx-size-lg)` square | Round icon slot. |
 | Item icon color | `var(--dsx-color-on-surface-variant)` | Quiet icon. |
 | Item content min-width | `min-width: 0` | Allows the title to ellipsis. |
+| Item content flex / row gap | `flex: 1 1 0`; `var(--dsx-space-sm)` | A short file row can shrink its text column before wrapping media/actions. FileUpload overrides Item's prose-oriented content basis. |
 | Item title overflow | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap` | Long file names truncate. |
 | Item media color | `var(--dsx-color-on-surface-variant)` | Quiet media. |
-| Item actions alignment | `margin-left: auto; flex-direction: column; align-items: flex-end; gap: var(--dsx-space-xs)` | Right-aligned, stacked. |
+| Item actions alignment | `margin-left: auto; flex-direction: column; flex-wrap: nowrap; align-items: flex-end; gap: var(--dsx-space-xs)` | Right-aligned, stacked. Consumer wrappers may define their own inner layout. |
 | Progress width | `width: 100%` | Full row width. |
 | Progress label/status typography | `var(--dsx-typography-label-small-*)` | Small label ramp. |
 | Progress label/status color | `var(--dsx-color-on-surface-variant)` | Quiet label. |
@@ -219,11 +225,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Composition story:**
 
-- Renders the full surface: dropzone, list, three items. The first item has a `progress={42}` with no label (the meta line carries the numbers, as in the reference). The second item has a `status="Complete"` and a ghost `IconButton` trash remove action. The third item has a `status="Upload failed"` with `statusTone="danger"` and ghost `IconButton` redo retry + trash remove actions. Asserts each slot renders with the right class, the progress bar renders, the failed row writes `data-status-tone="danger"`, and the actions block sits at the right edge with icons only.
+- One compact live capture surface populates dropzone, list, item, progress and working remove/retry actions after selection. An expandable row-state gallery shows progress, completed and failed rows, followed by forced drag feedback and Rift/Warp token stories. Size comparisons stay in the matrix rather than duplicating three large surfaces in the live example.
 
 **Live capture story:**
 
-- Renders `FileUploadLiveCapture`: a `multiple` dropzone with `onFiles` feeding a simulated upload list (interval-driven `progress` with reference-style `"X MB | Y% • Z sec left"` descriptions), an "Or upload from URL" `Input` + `Upload` `Button` composition appending completed rows, ghost `IconButton` row actions (trash remove always, redo retry on failed rows — retry resets the row to 0%), a fail preview (files with "fail" in the name fail at 60%), and a Cancel / Attach-files footer. Covered by `tests/file-upload.spec.ts` (drag capture, browse capture, zero console issues).
+- Renders `FileUploadLiveCapture` with `size="sm"`, `variant="filled"`, a short title/description and a working Browse files action. A `multiple` dropzone with `onFiles` feeds a simulated upload list (interval-driven progress). Compact rows use the existing `size="sm"` and `icon={null}` options, a file-size description, progress/completion/error status and stacked md ghost icon actions (trash remove always, redo retry on failed rows — retry resets the row to 0%). Files with "fail" in the name fail at 60%. Selection count is announced through a status region. Covered by `tests/file-upload.spec.ts` and `tests/sweep-polish.spec.ts` (drag/browse/keyboard capture, retry/remove, mobile geometry, zero console issues).
 
 **A11y story:**
 
@@ -253,7 +259,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Composed by consumers (not DS slots):**
 
-- URL upload (`Input` + `Button` appending a completed row) and modal shells with Cancel / Attach-files footers are app composition. The playground `FileUploadLiveCapture` fixture demonstrates both against the same list state.
+- URL fetching and modal shells with Cancel / Attach-files footers are app composition. The primary playground story focuses on file capture and rows; it does not imply FileUpload supplies a URL transport or an attach-to-record action.
 
 **Used by:**