@actioneer/ads 0.7.0 → 1.0.0

package/llms.txt

@@ -16,8 +16,8 @@
 ## Tokens
 
 Reference semantic roles, never raw color/dimension literals (ads-lint rejects literals). Each role produces `bg-/text-/border-<role>` utilities:
-- `background`
-- `foreground`
+- `background` — The shell canvas and its ink: the ground between top-level panels.
+- `foreground` — The shell canvas and its ink: the ground between top-level panels.
 - `on-white-primary` — Contextual text hierarchies — three accessible levels per surface.
 - `on-white-secondary` — Contextual text hierarchies — three accessible levels per surface.
 - `on-white-tertiary` — Contextual text hierarchies — three accessible levels per surface.
@@ -27,14 +27,14 @@ Reference semantic roles, never raw color/dimension literals (ads-lint rejects l
 - `primary` — Context-free compatibility aliases remain conservative.
 - `secondary` — Context-free compatibility aliases remain conservative.
 - `tertiary` — Context-free compatibility aliases remain conservative.
-- `surface`
-- `surface-foreground`
-- `elevated`
-- `muted`
-- `muted-foreground`
-- `card`
-- `card-foreground`
-- `specimen-stroke`
+- `surface` — One continuous recess inside a white surface, never a screen-level ground.
+- `surface-foreground` — One continuous recess inside a white surface, never a screen-level ground.
+- `elevated` — One continuous recess inside a white surface, never a screen-level ground.
+- `muted` — The hover and row-state wash: interaction, not a default item background.
+- `muted-foreground` — The hover and row-state wash: interaction, not a default item background.
+- `card` — The white working plane that sits on the canvas, and the specimen hairline.
+- `card-foreground` — The white working plane that sits on the canvas, and the specimen hairline.
+- `specimen-stroke` — The white working plane that sits on the canvas, and the specimen hairline.
 - `action-primary` — Primary CTA role — restrained Studio green, used sparingly.
 - `action-primary-foreground` — Primary CTA role — restrained Studio green, used sparingly.
 - `action-primary-hover` — Primary CTA role — restrained Studio green, used sparingly.
@@ -47,31 +47,31 @@ Reference semantic roles, never raw color/dimension literals (ads-lint rejects l
 - `brand-text` — Compatibility action role — neutral ink, never a colored primary hue.
 - `fill` — Quiet fill — avatars, chips, and disabled controls
 - `fill-foreground` — Quiet fill — avatars, chips, and disabled controls
-- `table-shell` — Quiet fill — avatars, chips, and disabled controls
-- `table-stroke` — Quiet fill — avatars, chips, and disabled controls
-- `table-header-foreground` — Quiet fill — avatars, chips, and disabled controls
-- `artifact-canvas`
-- `accent`
-- `accent-foreground`
-- `success` — Lichen success-700 clears AA on White and both success soft fills;
-- `success-foreground` — Lichen success-700 clears AA on White and both success soft fills;
-- `warning` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
-- `warning-foreground` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
-- `danger` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
-- `danger-foreground` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
-- `info` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
-- `info-foreground` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
-- `border-primary`
-- `border-secondary`
-- `border-tertiary`
-- `border`
-- `border-strong`
-- `input`
-- `menu-stroke`
-- `toast-stroke`
-- `tree-stroke`
-- `ring`
-- `overlay`
+- `table-shell` — Table surfaces: the white tray, its hairlines, and header ink.
+- `table-stroke` — Table surfaces: the white tray, its hairlines, and header ink.
+- `table-header-foreground` — Table surfaces: the white tray, its hairlines, and header ink.
+- `artifact-canvas` — The artifact sheet: white warmed by a trace of the brand mark.
+- `accent` — The active and selected wash, one step above hover.
+- `accent-foreground` — The active and selected wash, one step above hover.
+- `success` — Lichen success-700 clears AA on White and both success soft fills; success-600 is reserved for non-text marks because its 3.73:1 contrast on White does not clear body-text AA.
+- `success-foreground` — Lichen success-700 clears AA on White and both success soft fills; success-600 is reserved for non-text marks because its 3.73:1 contrast on White does not clear body-text AA.
+- `warning` — Amber-500 fill kept (it IS the caution signal); dark ink foreground instead of white = 6.94:1 (white on amber was 2.35:1, failed even 3:1).
+- `warning-foreground` — Amber-500 fill kept (it IS the caution signal); dark ink foreground instead of white = 6.94:1 (white on amber was 2.35:1, failed even 3:1).
+- `danger` — Danger and info: solid semantic fills carrying white foregrounds.
+- `danger-foreground` — Danger and info: solid semantic fills carrying white foregrounds.
+- `info` — Danger and info: solid semantic fills carrying white foregrounds.
+- `info-foreground` — Danger and info: solid semantic fills carrying white foregrounds.
+- `border-primary` — The neutral stroke ladder: every 1px UI border stays within WG3 to WG5.
+- `border-secondary` — The neutral stroke ladder: every 1px UI border stays within WG3 to WG5.
+- `border-tertiary` — The neutral stroke ladder: every 1px UI border stays within WG3 to WG5.
+- `border` — The neutral stroke ladder: every 1px UI border stays within WG3 to WG5.
+- `border-strong` — The neutral stroke ladder: every 1px UI border stays within WG3 to WG5.
+- `input` — The neutral stroke ladder: every 1px UI border stays within WG3 to WG5.
+- `menu-stroke` — The neutral stroke ladder: every 1px UI border stays within WG3 to WG5.
+- `toast-stroke` — The neutral stroke ladder: every 1px UI border stays within WG3 to WG5.
+- `tree-stroke` — The neutral stroke ladder: every 1px UI border stays within WG3 to WG5.
+- `ring` — Focus ring and scrim, both translucent warm ink.
+- `overlay` — Focus ring and scrim, both translucent warm ink.
 
 ## Design principles
 
@@ -97,7 +97,7 @@ Every surface defaults to shadow-0. Use the numbered elevation ladder only when
 - Do: When requested, use shadow-100 for controls, shadow-200 for raised surfaces and pressable cards, shadow-300 for menus, popovers, listboxes, and toasts, and shadow-400 for dialogs and overlay drawers.
 - Do: Reserve shadow-500 and shadow-600 for rare higher stacked layers; the legacy shadow-elevation hook resolves to shadow-0.
 - Don't: Infer permission to use a shadow from actionability, floating placement, or component type.
-- Don't: Use raw shadow values or legacy shadow-sm/md/lg/xl utilities.
+- Don't: Use raw shadow values or legacy named shadow utilities.
 - Don't: Put a shadow on a non-interactive surface for decoration.
 - Don't: Use shadow-500 or shadow-600 as a routine default.
 
@@ -115,15 +115,15 @@ Component motion follows the closest Animate UI interaction pattern, using role-
 - Don't: Animate keyboard-initiated or 100×/day actions (e.g. a command-palette toggle).
 - Don't: Add motion to a component only because it is visible; static structure and decorative chrome stay still.
 
-### 4. Icons: Hugeicons, stroke only [lint: icon-package-import]
+### 4. Icons: Phosphor, regular weight (fill for active) [lint: icon-package-import]
 
-All icons come from Hugeicons in the Stroke Rounded style only. Components import named icons from the @/lib/icons registry — never from an icon package directly — so a free→Pro swap or a restyle touches one file.
+All icons come from Phosphor Icons at the regular weight — the stroke-led icon language of ADS. Components import named icons from the @/lib/icons registry — never from an icon package directly — so swapping the underlying set touches one file.
 
-- Do: Import icons from the @/lib/icons registry; add a new one there (stroke variant) before using it.
+- Do: Import icons from the @/lib/icons registry; wrap a new Phosphor component with createIcon there before using it.
 - Do: Let icons default to size='1em' so they scale with text; size with a size prop or size-* class.
-- Do: Keep stroke weight at the drawn 1.5; strokeWidth={2} is the one sanctioned emphasis step.
-- Don't: Import from an icon package directly, or use solid/duotone/twotone/fill variants.
-- Don't: Use a stroke weight thinner than 1.5.
+- Do: Render weight='fill' for the active or selected state, and weight='bold' for the rare heavier stroke.
+- Don't: Import from an icon package directly, or install a second icon set.
+- Don't: Leave an active nav item's icon at the regular stroke weight.
 
 ### 5. Demo screens: the shell owns the frame [judgment]
 
@@ -142,13 +142,17 @@ Indicator/status dots (Badge & Chip dot variants, ConnectionStatus, chart legend
 
 ### 7. ADS-first UI: use the library; extend only when asked [lint: deep-import, barrel-aliased-import, barrel-default-import, barrel-namespace-import, external-ui-import]
 
-Every UI decision stays synchronized with ADS. Before making a new screen/control/pattern, check the ADS component suite first and use the exact exported name from the public barrel. Do not hand-roll, alias, deep-import, or import external UI libraries.
+Every UI decision stays synchronized with ADS. Search the full catalog before deciding a component is missing, and use the exact exported name from the public barrel. When the barrel genuinely has no primitive, the sanctioned fallback is a shadcn/ui component vendored into src/components/ui through the repo's components.json recipe — never a hand-rolled control and never a UI library imported at a call site.
 
 - Do: Use an existing ADS component by its exact exported name from the package barrel; compose existing components for layout-only patterns.
-- Do: Ask the user before extending ADS; only an explicit request authorizes new library work.
+- Do: Search the whole catalog before concluding a component is missing — the documented specimens are a sample, not the inventory.
+- Do: Fall back to shadcn/ui when the barrel has no primitive: vendor it with npx shadcn add into src/components/ui, import cn from @/lib/utils, and swap its lucide icons for @/lib/icons.
+- Do: Let a vendored shadcn component inherit the ADS palette through the shadcn-compat aliases in theme.css rather than restyling it by hand.
+- Do: Ask the user before promoting a vendored component into the public barrel; only an explicit request authorizes new library work.
 - Do: When authorized, add the component to the right family, export its exact name through the barrel, and document it.
 - Don't: Deep-import, alias, default/namespace-import, or hand-roll a local copy of a component.
-- Don't: Import a visual component directly from the web or an npm UI library.
+- Don't: Import a visual component directly from the web or an npm UI library at a call site.
+- Don't: Reach for the shadcn fallback before searching the catalog, or install a second component library beside it.
 
 ### 8. Minimal information per screen [judgment]
 
@@ -307,6 +311,7 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [NumberField] — Use for a bounded numeric quantity (e.g. seats, width, count) that benefits from stepper buttons and min/max clamping, not free-form numeric text entry. [docs](https://ads.actioneer.dev/#/number-field)
 - [Radio] — Use for choosing exactly one option from a small, fully visible set — wrap Radio options in a RadioGroup that owns the shared name and controlled value. [docs](https://ads.actioneer.dev/#/radio)
 - [RadioGroup] — component [docs](https://ads.actioneer.dev/#/radio)
+- [SearchDisclosure] — component [docs](https://ads.actioneer.dev/#/search-disclosure)
 - [SegmentedControl] — Use for a small set (2-4) of mutually exclusive, always-visible options — like a range or view-mode switcher — not for navigation or long lists. Radius follows control size: 4px at sm and 6px at md/lg; tracks and options are never fully rounded. (variants: size: sm|md|lg; selected: true|false) [docs](https://ads.actioneer.dev/#/segmented)
 - [Select] — Use for a single choice from a closed list of options in a form, especially when pairing with Field for a labeled control. (variants: size: sm|md|lg) [docs](https://ads.actioneer.dev/#/select)
 - [Slider] — Use for a single controlled numeric value picked from a bounded range (volume, brightness, threshold) — pair with Field or Label/Text for an accessible, labeled control. [docs](https://ads.actioneer.dev/#/slider)
@@ -324,6 +329,7 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [NumberFieldProps] — TypeScript type
 - [RadioGroupProps] — TypeScript type
 - [RadioProps] — TypeScript type
+- [SearchDisclosureProps] — TypeScript type
 - [SegmentedControlProps] — TypeScript type
 - [SegmentedOption] — TypeScript type
 - [SelectItem] — TypeScript type
@@ -347,7 +353,6 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [DropdownLabel] — component [docs](https://ads.actioneer.dev/#/dropdown)
 - [DropdownSeparator] — component [docs](https://ads.actioneer.dev/#/dropdown)
 - [DropdownTrigger] — component [docs](https://ads.actioneer.dev/#/dropdown)
-- [FloatingDrawer] — component (variants: side: right|left|bottom; size: sm|md|lg|xl) [docs](https://ads.actioneer.dev/#/drawer)
 - [InlineDrawer] — component (variants: side: right|left|bottom; size: sm|md|lg|xl) [docs](https://ads.actioneer.dev/#/drawer)
 - [Modal] — Use for a blocking, focused task or confirmation that must interrupt the page until resolved (portaled, focus-trapped, Escape/backdrop dismissible). (variants: size: sm|md|lg|xl|full; position: center|top) [docs](https://ads.actioneer.dev/#/modal)
 - [ModalBody] — component (variants: size: sm|md|lg|xl|full; position: center|top) [docs](https://ads.actioneer.dev/#/modal)
@@ -364,13 +369,11 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [ToastProvider] — component [docs](https://ads.actioneer.dev/#/toast)
 - [CommandPaletteItem] — TypeScript type
 - [CommandPaletteProps] — TypeScript type
-- [DrawerAppearance] — TypeScript type
 - [DrawerProps] — TypeScript type
 - [DropdownContentProps] — TypeScript type
 - [DropdownItemProps] — TypeScript type
 - [DropdownProps] — TypeScript type
 - [DropdownTriggerProps] — TypeScript type
-- [FloatingDrawerProps] — TypeScript type
 - [InlineDrawerProps] — TypeScript type
 - [ModalBodyProps] — TypeScript type
 - [ModalDrawerProps] — TypeScript type
@@ -453,7 +456,7 @@ Before using any component below, preserve its built-in motion and apply the mot
 - [SeriesChart] — component [docs](https://ads.actioneer.dev/#/viz-charts)
 - [StatusAnswer] — component (variants: tone: default|primary|success|warning|danger|info) [docs](https://ads.actioneer.dev/#/ai/answer)
 - [Tab] — component (variants: orientation: horizontal|vertical; selected: true|false) [docs](https://ads.actioneer.dev/#/tabs)
-- [Table] — Use Table for structured tabular data that may need row selection, column sorting, sticky columns, or a paginated footer — not for simple key-value lists. Interactive rows inherit the shared soft neutral hover/focus sink and keep their normal table geometry; do not add a brand tint or hover-only corner rounding. Primary record links stay text-only in every state: never reveal an arrow, chevron, or other directional icon only on hover. Persistent row actions use a final sticky-right column plus elevatedActionColumn so one body-column shadow lifts the action surface instead of repeating on individual cells. The empty matching header cell remains transparent and non-sticky. [docs](https://ads.actioneer.dev/#/table)
+- [Table] — Use Table for structured tabular data that may need row selection, column sorting, sticky columns, or a paginated footer — not for simple key-value lists. Every primary body-cell value defaults to text-m (14px / 20px); only clearly secondary metadata inside a cell may opt down to text-s. Interactive rows inherit the shared soft neutral hover/focus sink and keep their normal table geometry; do not add a brand tint or hover-only corner rounding. Primary record links stay text-only in every state: never reveal an arrow, chevron, or other directional icon only on hover. Persistent row actions use a final sticky-right column plus elevatedActionColumn so one body-column shadow lifts the action surface instead of repeating on individual cells. The empty matching header cell remains transparent and non-sticky. [docs](https://ads.actioneer.dev/#/table)
 - [TableAnswer] — component (variants: tone: default|primary|success|warning|danger|info) [docs](https://ads.actioneer.dev/#/ai/answer)
 - [TableBody] — component [docs](https://ads.actioneer.dev/#/table)
 - [TableCell] — component [docs](https://ads.actioneer.dev/#/table)