@jaimevalasek/aioson 1.30.1 → 1.30.2

package/template/.aioson/skills/design/interface-design/references/tokens-and-depth.md

@@ -1,173 +1,173 @@
-# Tokens and Depth — Interface Design
-
-Lock these decisions before implementation. If you cannot state the checkpoint clearly, the system is not ready to build.
-
----
-
-## Decision checkpoint (write this before any component)
-
-Before building any screen or component family, write a short checkpoint that locks:
-
-- **Depth strategy**
-- **Surface levels**
-- **Border recipe** (including alpha)
-- **Spacing base**
-- **Radius ladder**
-- **Control height**
-- **Typography anchor**
-- **Motion posture**
-
-Example (Sophistication & Trust):
-> Depth: borders-only • Surfaces: base / surface / elevated • Borders: rgba(15,23,42,0.08) • Spacing: 8px • Radius: 10/12 • Controls: 38px • Type: IBM Plex Sans 14/16/24 • Motion: 120ms ease-out
-
-Example (Premium Dark Platform):
-> Depth: borders-first • Surfaces: #0b1015 / #10161d / #151c24 • Borders: rgba(255,255,255,0.08) • Spacing: 8px • Radius: 12/14 • Controls: 40px • Type: Geist 14/16/28 • Motion: 140ms ease-out
-
----
-
-## Token architecture (define all levels)
-
-### Color token families
-
-```
-foreground/primary     ← body text, labels, high-emphasis
-foreground/secondary   ← supporting text, placeholders
-foreground/muted       ← captions, disabled labels
-foreground/faint       ← decorative only, never critical
-
-background/base        ← page background
-background/surface     ← cards, panels
-background/elevated    ← modals, dropdowns (shadow system) or third surface level
-background/sunken      ← inputs, inset areas
-
-border/default         ← standard separator
-border/strong          ← focused inputs, active states
-border/faint           ← ultra-subtle dividers
-
-brand/primary          ← main CTA color
-brand/secondary        ← supporting brand accent
-
-semantic/success       ← green family
-semantic/warning       ← amber family
-semantic/danger        ← red family
-semantic/info          ← blue family
-```
-
-### Spacing — base × multiples only
-
-Never use arbitrary values (17px, 22px, 37px). Every value must be a multiple of your base.
-
-Common bases:
-- 4px base for dense/operational: 4, 8, 12, 16, 24, 32
-- 4px base for generous/consumer: 8, 12, 16, 24, 32, 48
-
-### Depth — pick ONE and commit
-
-| Strategy | When | Implementation |
-|---|---|---|
-| **Borders only** | Maximum density, zero visual noise | `border: 1px solid border/faint` |
-| **Subtle shadows** | Gentle, approachable feel | `box-shadow: 0 1px 3px rgba(0,0,0,0.08)` |
-| **Layered surfaces** | Modern minimal, dark platforms | Background elevation without shadows or borders |
-
-**Never mix depth strategies on the same surface.**
-
-### Radius ladder
-
-Define three values and use only them:
-- Sharp (small controls, tags, badges)
-- Medium (cards, inputs, buttons)
-- Large (panels, modals, sheets)
-
-### Typography anchor
-
-Define one font family and its full scale before touching components:
-
-```
-Page title    : largest size, 600-weight, tight tracking
-Section title : medium-large, 500-weight, normal tracking
-Body          : base size, 400-weight, line-height 1.5–1.6
-Helper / meta : small, 400-weight, muted color
-Data / mono   : monospace for numbers in tables, code, metrics
-```
-
-Size alone is never enough. Use weight + tracking + opacity to create layers.
-
-### Motion posture
-
-- Fast & utilitarian: 100–150ms ease-out
-- Comfortable & polished: 140–200ms ease-out
-- Expressive & refined: 200–300ms ease-out with spring for entrances
-
-Never animate layout properties (width, height, padding). Animate `transform` and `opacity` only.
-Always provide `prefers-reduced-motion: reduce` fallback.
-
----
-
-## Operational density — admin / config / settings pages
-
-Settings pages, admin panels, config screens, and entity managers use a **compact scale** that overrides the default generous consumer spacing. Apply this whenever the user is operating a tool, not reading content.
-
-### Decision checkpoint for operational density
-
-> Depth: borders-first • Surfaces: 3-level (page / card / elevated) • Spacing base: 4px • Controls: 32px • Card padding: 16px outer / 12px nested • Type: xs-base range, text-base max for card headings • Radius: 22px outer / 18px nested / 14px deep
-
-### Card padding — 3-level scale
-
-| Level | Context | Padding | Radius |
-|---|---|---|---|
-| L1 | top-level section card | `16px` | `22px` |
-| L2 | card nested inside L1 | `12px` | `18px` |
-| L3 | inset block, disclosure body | `10px` | `14px` |
-
-Section gap: `12px` — not 16px or 24px.
-
-### Card headings
-
-- Section eyebrow: `0.68rem` uppercase mono, `tracking: 0.28em`
-- Section title: `text-base` (15–16px), `font-weight: 600` — **never `text-xl` or `text-2xl` inside a card**
-- Sub-info (path, ID): `font-mono text-[0.62rem]` single truncated line below title — no card for it
-- **No verbose description paragraphs** in admin cards — remove them or collapse to `<details>`
-
-### Form controls
-
-```
-Label  : 10–11px  margin-bottom: 2px
-Input  : px-3 py-2  (height ~32px)  text-xs  radius: 10–12px
-Select : same
-Button : px-3 py-2  text-xs  radius: 10–12px
-```
-
-The default 40px `min-height` rule in `## Forms` applies to consumer/public-facing forms. Admin/operational forms use 32px controls. Reduce only in authenticated tool contexts — never on public-facing login or onboarding.
-
-### List rows
-
-```
-Row     : py-2 (8px)  divide-y
-Gap     : gap-2.5
-Name    : text-xs font-medium  — not text-sm
-Model   : font-mono text-[0.65rem]  truncate
-Badges  : px-2 py-0.5 text-[0.6rem]  — not px-3 py-1
-Edit btn: px-2.5 py-1 text-[0.65rem]
-```
-
-### Entity grids (same-type objects: projects, agents, providers)
-
-Never stack same-type entities full-width. Use:
-```css
-grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
-gap: 12px;
-/* Entity card: rounded-[18px] p-3 */
-```
-
-### Add/Edit → Modal, not accordion
-
-Inline form expansion (accordion, RevealPanel) inside entity cards creates visual clutter and unpredictable layout shifts. Use a modal:
-- `max-width: 448px`, centered, backdrop `bg-black/50 backdrop-blur-sm`
-- Single "+ Add" button outside the grid → opens modal
-- "Edit" button on each card → same modal pre-filled
-
-### Disclosure for secondary tools
-
-Sync assistants, cloud connect, advanced config, and other secondary actions go behind `<details>`:
-- Summary row: `flex items-center justify-between px-3 py-2.5` — label + status badge on left, action button on right
-- Never show secondary tools open by default in an already-dense panel
+# Tokens and Depth — Interface Design
+
+Lock these decisions before implementation. If you cannot state the checkpoint clearly, the system is not ready to build.
+
+---
+
+## Decision checkpoint (write this before any component)
+
+Before building any screen or component family, write a short checkpoint that locks:
+
+- **Depth strategy**
+- **Surface levels**
+- **Border recipe** (including alpha)
+- **Spacing base**
+- **Radius ladder**
+- **Control height**
+- **Typography anchor**
+- **Motion posture**
+
+Example (Sophistication & Trust):
+> Depth: borders-only • Surfaces: base / surface / elevated • Borders: rgba(15,23,42,0.08) • Spacing: 8px • Radius: 10/12 • Controls: 38px • Type: IBM Plex Sans 14/16/24 • Motion: 120ms ease-out
+
+Example (Premium Dark Platform):
+> Depth: borders-first • Surfaces: #0b1015 / #10161d / #151c24 • Borders: rgba(255,255,255,0.08) • Spacing: 8px • Radius: 12/14 • Controls: 40px • Type: Geist 14/16/28 • Motion: 140ms ease-out
+
+---
+
+## Token architecture (define all levels)
+
+### Color token families
+
+```
+foreground/primary     ← body text, labels, high-emphasis
+foreground/secondary   ← supporting text, placeholders
+foreground/muted       ← captions, disabled labels
+foreground/faint       ← decorative only, never critical
+
+background/base        ← page background
+background/surface     ← cards, panels
+background/elevated    ← modals, dropdowns (shadow system) or third surface level
+background/sunken      ← inputs, inset areas
+
+border/default         ← standard separator
+border/strong          ← focused inputs, active states
+border/faint           ← ultra-subtle dividers
+
+brand/primary          ← main CTA color
+brand/secondary        ← supporting brand accent
+
+semantic/success       ← green family
+semantic/warning       ← amber family
+semantic/danger        ← red family
+semantic/info          ← blue family
+```
+
+### Spacing — base × multiples only
+
+Never use arbitrary values (17px, 22px, 37px). Every value must be a multiple of your base.
+
+Common bases:
+- 4px base for dense/operational: 4, 8, 12, 16, 24, 32
+- 4px base for generous/consumer: 8, 12, 16, 24, 32, 48
+
+### Depth — pick ONE and commit
+
+| Strategy | When | Implementation |
+|---|---|---|
+| **Borders only** | Maximum density, zero visual noise | `border: 1px solid border/faint` |
+| **Subtle shadows** | Gentle, approachable feel | `box-shadow: 0 1px 3px rgba(0,0,0,0.08)` |
+| **Layered surfaces** | Modern minimal, dark platforms | Background elevation without shadows or borders |
+
+**Never mix depth strategies on the same surface.**
+
+### Radius ladder
+
+Define three values and use only them:
+- Sharp (small controls, tags, badges)
+- Medium (cards, inputs, buttons)
+- Large (panels, modals, sheets)
+
+### Typography anchor
+
+Define one font family and its full scale before touching components:
+
+```
+Page title    : largest size, 600-weight, tight tracking
+Section title : medium-large, 500-weight, normal tracking
+Body          : base size, 400-weight, line-height 1.5–1.6
+Helper / meta : small, 400-weight, muted color
+Data / mono   : monospace for numbers in tables, code, metrics
+```
+
+Size alone is never enough. Use weight + tracking + opacity to create layers.
+
+### Motion posture
+
+- Fast & utilitarian: 100–150ms ease-out
+- Comfortable & polished: 140–200ms ease-out
+- Expressive & refined: 200–300ms ease-out with spring for entrances
+
+Never animate layout properties (width, height, padding). Animate `transform` and `opacity` only.
+Always provide `prefers-reduced-motion: reduce` fallback.
+
+---
+
+## Operational density — admin / config / settings pages
+
+Settings pages, admin panels, config screens, and entity managers use a **compact scale** that overrides the default generous consumer spacing. Apply this whenever the user is operating a tool, not reading content.
+
+### Decision checkpoint for operational density
+
+> Depth: borders-first • Surfaces: 3-level (page / card / elevated) • Spacing base: 4px • Controls: 32px • Card padding: 16px outer / 12px nested • Type: xs-base range, text-base max for card headings • Radius: 22px outer / 18px nested / 14px deep
+
+### Card padding — 3-level scale
+
+| Level | Context | Padding | Radius |
+|---|---|---|---|
+| L1 | top-level section card | `16px` | `22px` |
+| L2 | card nested inside L1 | `12px` | `18px` |
+| L3 | inset block, disclosure body | `10px` | `14px` |
+
+Section gap: `12px` — not 16px or 24px.
+
+### Card headings
+
+- Section eyebrow: `0.68rem` uppercase mono, `tracking: 0.28em`
+- Section title: `text-base` (15–16px), `font-weight: 600` — **never `text-xl` or `text-2xl` inside a card**
+- Sub-info (path, ID): `font-mono text-[0.62rem]` single truncated line below title — no card for it
+- **No verbose description paragraphs** in admin cards — remove them or collapse to `<details>`
+
+### Form controls
+
+```
+Label  : 10–11px  margin-bottom: 2px
+Input  : px-3 py-2  (height ~32px)  text-xs  radius: 10–12px
+Select : same
+Button : px-3 py-2  text-xs  radius: 10–12px
+```
+
+The default 40px `min-height` rule in `## Forms` applies to consumer/public-facing forms. Admin/operational forms use 32px controls. Reduce only in authenticated tool contexts — never on public-facing login or onboarding.
+
+### List rows
+
+```
+Row     : py-2 (8px)  divide-y
+Gap     : gap-2.5
+Name    : text-xs font-medium  — not text-sm
+Model   : font-mono text-[0.65rem]  truncate
+Badges  : px-2 py-0.5 text-[0.6rem]  — not px-3 py-1
+Edit btn: px-2.5 py-1 text-[0.65rem]
+```
+
+### Entity grids (same-type objects: projects, agents, providers)
+
+Never stack same-type entities full-width. Use:
+```css
+grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+gap: 12px;
+/* Entity card: rounded-[18px] p-3 */
+```
+
+### Add/Edit → Modal, not accordion
+
+Inline form expansion (accordion, RevealPanel) inside entity cards creates visual clutter and unpredictable layout shifts. Use a modal:
+- `max-width: 448px`, centered, backdrop `bg-black/50 backdrop-blur-sm`
+- Single "+ Add" button outside the grid → opens modal
+- "Edit" button on each card → same modal pre-filled
+
+### Disclosure for secondary tools
+
+Sync assistants, cloud connect, advanced config, and other secondary actions go behind `<details>`:
+- Summary row: `flex items-center justify-between px-3 py-2.5` — label + status badge on left, action button on right
+- Never show secondary tools open by default in an already-dense panel