@ttoss/fsl-ui 0.2.4 → 0.2.6

package/src/tokens/CONTRACT.md

@@ -112,7 +112,7 @@ The grouping criterion is a single discriminant question:
 
 **Stacking inside `informational`.** When two `informational` surfaces overlap (Card inside Dialog, Dialog over page, …) they may resolve to the same `background` colour. Differentiation is paid in `elevation` first, `border` second, never in colour. See [colors.md → Stacking informational surfaces](/docs/design/design-system/design-tokens/colors#stacking-informational-surfaces) for the operational rule.
 
-**Collection containers with Selection items (per-part entity split).** A selectable list composite (`ListBox`, `GridList`) is allowed to declare **two entities across its parts**: the container root is `Collection` (an `informational` surface — the frame that carries the items) while each selectable item is `Selection` (`input` chrome, `selected` State). The item's selection chrome is therefore identical to `Select`/`Checkbox`/`RadioGroup` (`vars.colors.input.*`), and the container reads `vars.colors.informational.*`. This is intentional and enforced-compatible: the entity→ux-context contract test unions the contexts of all entities declared in a file, so both reads are legal. See ADR-007 for the rationale.
+**Collection containers with Selection items (per-part entity split).** A selectable list composite (`ListBox`, `GridList`, `Table`) is allowed to declare **two entities across its parts**: the container root is `Collection` (an `informational` surface — the frame that carries the items) while each selectable item is `Selection` (`input` chrome, `selected` State). The item's selection chrome is therefore identical to `Select`/`Checkbox`/`RadioGroup` (`vars.colors.input.*`), and the container reads `vars.colors.informational.*`. This is intentional and enforced-compatible: the entity→ux-context contract test unions the contexts of all entities declared in a file, so both reads are legal. See ADR-007 for the rationale. `Table` extends the split with two Collection parts: `TableColumn` is the `title` structural role (columnheader; sortable columns render the `action.sortAscending`/`action.sortDescending` Icon intents) and `TableCell` is `content` — the ROADMAP B2 mapping, no taxonomy addition needed.
 
 **Surface type rule** (derives all non-color columns):
 
@@ -294,13 +294,21 @@ color:           resolveInteractiveStyle(c?.text,       { isHovered, isPressed,
 
 | Family     | Standard step | Token path                                 |
 | ---------- | ------------- | ------------------------------------------ |
-| Sizing     | `base`        | `vars.sizing.hit.base`                     |
+| Sizing     | _(single)_    | `vars.sizing.hit`                          |
 | Spacing    | `md`          | `vars.spacing.inset.{control\|surface}.md` |
 | Typography | `md`          | `vars.text.label.md`                       |
 
 If a design calls for a "small button", the question is: **why is it smaller semantically?**
 Is it a toolbar action? A chip? A compact selection control? Name it, give it an entity, and it gets its own fixed step.
 
+> **Layout is not a control.** The "no size prop" rule governs _interactive_
+> components (Entity ≠ Structure). The presentational layer — `Box`, `Grid`,
+> `Container`, `Stack`, `Surface` (all Entity = `Structure`) — is the sanctioned,
+> **token-constrained** escape hatch (ADR-009): its props accept only token keys
+> (`padding="md"`, `columns={3}`, `maxWidth="reading"`) or layout keywords
+> (`align`, `auto`/`100%`/`fit-content`), never a raw `style`/`className`/hex/px.
+> Compose layouts with these instead of hand-rolling CSS.
+
 ---
 
 ## §5 — data-\* Attribute Convention
@@ -349,7 +357,18 @@ const valid = ENTITY_EVALUATION['Action'];
 
 ---
 
-## §7 — Escape Hatches: Composite-Scoped CSS Custom Properties
+## §7 — Escape Hatches
+
+There are **two** sanctioned escape hatches, for two different needs:
+
+1. **Composition → the presentational layer (ADR-009).** To arrange, pad, size,
+   or lightly group content, use `Box`/`Grid`/`Container`/`Stack`/`Surface`
+   (Entity = `Structure`). Their props are token-constrained (token keys +
+   layout keywords only) — this is the answer to "I need custom layout" and
+   replaces hand-rolled CSS. See §4.
+2. **Host geometry on composites → composite-scoped CSS custom properties.**
+   For host-owned geometry knobs on interactive composites (which own their
+   layout and expose no visual props), the single channel is described below.
 
 Composites own their layout: they expose no `style`/`className` and no
 visual props. The **single sanctioned customization channel** is a
@@ -407,7 +426,7 @@ Registered knobs:
 ## §8 — Full Example: Button (Entity = Action)
 
 `entity: 'Action'` → §1 row: colors=`action`, radii=`control`, border=`outline.control`,
-sizing=`hit.base`, spacing=`inset.control.md`, typography=`label.md`, motion=`feedback`, elevation=`flat`.
+sizing=`hit`, spacing=`inset.control.md`, typography=`label.md`, motion=`feedback`, elevation=`flat`.
 
 ```typescript
 import { vars } from '@ttoss/fsl-theme/vars';
@@ -440,7 +459,7 @@ export const Button = ({ evaluation = 'primary', ...props }: ButtonProps) => {
         borderRadius: vars.radii.control,
         borderWidth: vars.border.outline.control.width,
         borderStyle: vars.border.outline.control.style,
-        minHeight: vars.sizing.hit.base,
+        minHeight: vars.sizing.hit,
         paddingBlock: vars.spacing.inset.control.md,
         paddingInline: vars.spacing.inset.control.md,
         ...(vars.text.label.md as React.CSSProperties),
@@ -471,15 +490,14 @@ export const Button = ({ evaluation = 'primary', ...props }: ButtonProps) => {
 
 ---
 
-## §9 — Icons (internal glyph layer)
+## §9 — Icons (semantic glyph layer; public since ADR-010)
 
 When a component needs a glyph (chevron, check, close, …), do **not** hardcode
-a unicode character or hand-author SVG. Use the internal `Icon`
-(`src/components/Icon/`) — a semantic layer over the Iconify provider
-(ADR-005):
+a unicode character or hand-author SVG. Use `Icon` — a semantic layer over
+the Iconify provider (ADR-005; public export per ADR-010):
 
 ```typescript
-import { Icon } from '../Icon'; // from src/components/*; '../../components/Icon' from composites
+import { Icon } from '@ttoss/fsl-ui'; // inside this package: '../Icon' from src/components/*
 
 <Icon intent="disclosure.expand" />          // named by meaning, not glyph
 <Icon intent="action.close" size="sm" />     // sm | md (default) | lg → vars.sizing.icon.*