@tidyfactor/design 1.5.0

package/references/commands/school.md

@@ -0,0 +1,41 @@
+# Command: `school` — Conscious Design Direction
+
+## Purpose
+Force a named, justified aesthetic choice before any token or component
+exists — the single biggest lever against a prototype defaulting to
+generic AI-generated design patterns (see `memory/01-design-schools.md` for
+the calibration list of overused defaults to actively avoid unless the brief
+asks for them specifically).
+
+## When to run it
+- Always, as part of `init`, before `tokens`.
+- The prototype "feels generic" or "could be any brand" — re-run to
+  re-anchor the direction.
+- User phrasing: "make this feel more [X]", "pick a design direction",
+  `school`.
+
+## What it does
+1. Read the brief's subject matter, audience, and any stated visual
+   references. If the brief pins down a direction, follow it exactly.
+2. Where the brief leaves it open, choose deliberately from `memory/16-design-movements-guide.md` (all 20 Visual Aesthetics & Design Movements: Swiss, Flat, Material, Minimalism, Brutalism/Neo-Brutalism, Bauhaus, Skeuomorphism, Glassmorphism, Maximalism, Industrial, Bento Box, Aurora Mesh, Neumorphism, Corporate Memphis, Cyberpunk, Claymorphism, Isometric, Kinetic Typography, Organic/Amorphous, Frutiger Aero/Y2K) and `memory/17-storytelling-industries-ux.md` (4 Storytelling Archetypes, 8 Industry Registers, 8 UX Philosophies) — never by defaulting to whichever is most common in training data.
+3. **Actively avoid** the three AI-design tells unless the brief calls for
+   one specifically: warm-cream + terracotta serif, near-black + single
+   acid accent, broadsheet-hairline-columns-everywhere applied
+   indiscriminately regardless of subject.
+4. Document the choice in one short paragraph: which school, why it fits
+   this subject/audience, and the one signature element the direction will
+   be remembered by.
+5. This decision governs every later token value and component style —
+   `tokens`/`components` implement it, they don't re-decide it.
+
+## Output convention
+```
+design-system/brand.json
+  "school": { "direction": "...", "rationale": "...", "signatureElement": "..." }
+```
+
+## Checklist
+- [ ] Direction is a real choice made for this subject, not a default
+- [ ] Signature element identified — the one thing this prototype will be
+      remembered by
+- [ ] Decision recorded in `brand.json`, not left implicit in code

package/references/commands/states.md

@@ -0,0 +1,48 @@
+# Command: `states` — Interactive States, Not a Static Mockup
+
+## Purpose
+This is what separates an "interactive prototype" from a picture of a
+website — the difference the whole positioning of this skill depends on.
+Kept as its own command because states are easy to skip under time
+pressure and easy to audit for once isolated.
+
+## When to run it
+- After a component/page/screen has its default look — always follow with
+  a states pass before calling it done.
+- User phrasing: "add hover states", "what does this look like empty/
+  loading", `states`.
+
+## What it does
+1. For every interactive component in scope, confirm the full matrix
+   applies where relevant: default, hover, focus-visible, active/pressed,
+   disabled, loading, empty, error, success.
+2. Implement via `interactions.js` (shared) for stateful JS behavior
+   (dropdown open/close, tab switching, modal show/hide, toast
+   dismiss) and CSS pseudo-classes for the rest — never a per-page
+   `<script>` for one page's interactive widget.
+3. **Empty states are a design decision, not a placeholder**: what caused
+   it, what the user should do next — same principle as `frontend-design`'s
+   "an empty screen is an invitation to act", applied consistently across
+   the whole prototype rather than per page.
+4. **Loading states**: skeleton shapes matching the eventual content's
+   layout, not a generic spinner-only blank — this is what makes a
+   dashboard prototype credible.
+5. Keyboard/focus-visible states are not optional — every interactive
+   element needs a visible focus ring using a token color, not the browser
+   default.
+
+## Output convention
+```
+design-system/
+  components.css     ← :hover, :focus-visible, [disabled], .is-loading, .is-empty, .is-error
+  interactions.js      ← shared stateful behavior (toggle/modal/dropdown/tab)
+```
+
+## Checklist
+- [ ] Hover, focus-visible, active, and disabled states present on every
+      interactive component
+- [ ] Empty and loading states designed deliberately, not left as
+      placeholders
+- [ ] Stateful behavior lives in shared `interactions.js`, never a
+      per-page script
+- [ ] Focus ring visible and token-colored on every focusable element

package/references/commands/study.md

@@ -0,0 +1,98 @@
+# Command: `study` — Design DNA Extraction & Competitive Analysis
+
+Runtime entry point for extracting design DNA from a live URL, screenshot, or reference site. Part of the **Discovery** lifecycle phase.
+
+## When to use
+
+- Before starting any new design project (run `study` → then `brief` → then `init`)
+- When reverse-engineering a competitor's design language
+- When a client says "make it feel like [reference]"
+
+## Dispatch Steps
+
+1. Load `memory/06-quality-bar.md` — anti-slop awareness (so the study doesn't praise AI patterns).
+2. Load `memory/01-design-schools.md` — classify the reference into a design movement.
+3. Execute the DNA extraction protocol below.
+4. Output a diagnosis report — user decides next step.
+
+## DNA Extraction Protocol
+
+### Input
+One of:
+- **Live URL** → browse the page, capture computed styles, screenshot sections
+- **Screenshot / image** → visual analysis only (less precise on exact hex values)
+- **Multiple URLs** → cross-reference to find the shared design language
+
+### Extraction Axes (6 Dimensions)
+
+| Axis | What to extract | How to extract |
+|---|---|---|
+| **Macrostructure** | Section rhythm, hero type, scroll behavior | Map each viewport-height section, note sticky/parallax/pinned |
+| **Color Anchor** | Primary, surface, text, accent colors | Computed styles from `getComputedStyle()` on buttons, headers, body, backgrounds — NOT visual guesses from screenshots |
+| **Type Pairing** | Heading family, body family, weight usage | `<link>` and `@font-face` declarations, NOT visual matching |
+| **Spacing System** | Base unit, scale pattern, section gaps | Measure actual padding/margin values on key containers |
+| **Motion Register** | Entrance style, scroll interaction, transition timing | Observe scroll behavior, hover states, page transitions |
+| **Component DNA** | Card style, button shape, nav pattern, footer pattern | Classify against the catalogs in `memory/14-nav-footer-catalog.md` |
+
+### Critical Rules
+- **Sample computed styles** (actual rendered hex values from buttons, headers, body text) — never guess from a screenshot's visual impression.
+- **Extract font family names** from `<link>`/`@font-face` declarations — never from visual matching.
+- **Do NOT extract layout structure** — the reference site's section order is not a design token; the engine's layout archetypes (`memory/13-layout-archetypes.md`) own that decision.
+- **Do NOT extract literal copy text** — voice *rules* transfer (tone, banned words), literal sentences don't.
+
+## Output: Design DNA Report
+
+```markdown
+## Design DNA Report: [Reference Name]
+
+### Classification
+- **Design School**: [from 01-design-schools.md]
+- **Genre**: editorial / modern-minimal / atmospheric / playful / luxury / industrial
+- **Mood**: [2-3 adjective tone words]
+
+### Color Anchor
+| Token | Hex | Source |
+|---|---|---|
+| primary | #XXXXXX | computed: button background |
+| surface | #XXXXXX | computed: card background |
+| text | #XXXXXX | computed: body color |
+| accent | #XXXXXX | computed: link/highlight color |
+
+### Type Pairing
+- Heading: [Family] (weight [N])
+- Body: [Family] (weight [N])
+- Source: [<link> tag / @font-face / Google Fonts import]
+
+### Spacing System
+- Base unit: [N]px
+- Section gaps: [pattern]
+
+### Motion Register
+- Entrance: [fade-up / clip-reveal / slide / none]
+- Scroll: [sticky / parallax / scroll-snap / standard]
+- Hover: [lift / scale / glow / none]
+
+### Component DNA
+- Nav: [N1–N9 from catalog]
+- Footer: [Ft1–Ft8 from catalog]
+- Cards: [elevation / bordered / flat / glassmorphic]
+- Buttons: [rounded / pill / square / ghost]
+
+### Anti-Pattern Tells Detected
+- [List any of the 16 AI tells found in the reference]
+```
+
+## User Decision After Report
+
+The user can:
+1. **Lock** the DNA into a `design.md` project brief → flow into `init`
+2. **Cherry-pick** specific axes (e.g., "use their color anchor but our own typography")
+3. **Stop** at diagnosis — study is complete
+
+## Checklist
+
+- [ ] Color values extracted from computed styles, not visual guesses
+- [ ] Font families extracted from `<link>`/`@font-face`, not visual matching
+- [ ] Layout structure NOT carried over — only tokens
+- [ ] Report classifies against design schools and anti-pattern catalogs
+- [ ] User presented with 3 clear next-step options

package/references/commands/tokens.md

@@ -0,0 +1,45 @@
+# Command: `tokens` — Design Tokens & `brand.json`
+
+## Purpose
+Establish the single source of truth every other command reads from. This
+is the one command every later command depends on — re-running it (a
+rebrand, a palette fix) is how a change propagates to every page at once.
+
+## When to run it
+- Start of `init` — always first, right after `school`.
+- The user says "update the brand colors", "adjust the type scale",
+  "we rebranded", `tokens`.
+
+## What it does
+1. Derive token categories from the `school` decision and brief:
+   - `colors` — primary/secondary/accent + light/dark surface scales
+   - `typography` — display/body/mono families, a type scale (not
+     arbitrary per-heading sizes), weights
+   - `spacing` — a consistent scale (e.g. 4px base), not ad hoc values
+   - `radius`, `shadow` — a small fixed set, not one-off values per
+     component
+   - `motion` — duration/easing tokens (feeds `motion` command)
+2. Write `design-system/tokens.css` as `:root` custom properties (Native/
+   Hybrid), or the equivalent theme-config object (Tailwind), or the
+   `[data-theme]` block (daisyUI) — per `references/foundations/<choice>.md`.
+3. Write/update `design-system/brand.json`: `meta.*`, `colors.*`,
+   `typography.*`, `spacing.*`, `voice.*` (copy tone/register), `cssFoundation`,
+   `localization.*` (default locale, RTL locales — see `i18n`).
+4. **If tokens.css already exists and pages already reference it**: this is
+   a propagating change — flag every existing page for re-verification
+   after the update, don't silently assume they still look correct.
+
+## Output convention
+```
+design-system/
+  tokens.css     ← :root custom properties (or foundation-equivalent)
+  brand.json     ← structured source; tokens.css is generated to match it
+```
+
+## Checklist
+- [ ] Every token category present: colors, typography, spacing, radius,
+      shadow, motion
+- [ ] `cssFoundation` recorded in `brand.json` and matches the project's
+      actual `<head>` includes
+- [ ] If tokens changed on an existing project, affected pages flagged for
+      re-verification

package/references/commands/typography.md

@@ -0,0 +1,87 @@
+# Command: `typography` — Mood-Routed Typography Pairing
+
+Runtime entry point for selecting and configuring typography pairings based on project mood, layout archetype, and language requirements. Part of the **Foundation** lifecycle phase.
+
+## When to use
+
+- During `init` or `brand` when choosing fonts
+- When the default pair (El Messiri + Tajawal) doesn't match the project mood
+- When switching between layout archetypes that call for different type registers
+- When adding a new locale or adjusting Arabic typography weight
+
+## Dispatch Steps
+
+1. Load `memory/12-typography-matrix.md` — the mood → pairing matrix.
+2. Load `memory/08-arabic-bilingual.md` — Arabic/RTL base rules.
+3. Identify the project mood from `brief` output or user description.
+4. Route to the matching pairing row.
+5. Update `brand.json` `typography.families` and `googleFontsUrl`.
+
+## The Mood → Typography Matrix
+
+| Mood | Arabic Heading | Arabic Body | Latin Accent | Best Layouts | Avoid For |
+|---|---|---|---|---|---|
+| **Default luxury** (safe, warm) | El Messiri | Tajawal | Cormorant Garamond | any | — |
+| **Editorial / literary** | Markazi Text | IBM Plex Sans Arabic | Fraunces | `story` (editorial) | `app` (too soft for UI chrome) |
+| **Art-Deco / high fashion** | Jomhuria *(display ≥48px only)* | Cairo | Bodoni Moda | `film` (fullbleed) | `creator` (too loud for quiet page) |
+| **Modern minimal / tech** | Cairo | Cairo (weight-differentiated) | Marcellus | `app` (interface), `creator` (minimal) | `space` (reads cold for real estate) |
+| **Warm hospitality / travel** | El Messiri | Almarai | Prata | `space` (spatial) | — |
+| **E-Commerce & conversion** | El Messiri | Tajawal | Cormorant Garamond | `product`, `store` | — |
+| **Automotive / performance** | El Messiri + Oswald (numerals) | Tajawal | Oswald | `film`, `story` (auto use case) | non-automotive builds |
+
+## Font Rules
+
+### Hard constraints (from `memory/06-quality-bar.md`)
+- **Never Amiri** for headings above ~24px — too calligraphic for display text
+- **Never manuscript/Naskh** faces above ~24px, regardless of which pair is chosen
+- **Display-only faces** (e.g., Jomhuria) must NOT be used for body copy or long captions
+- All fonts must be **Google Fonts** (CDN-only, no self-hosting, no build step)
+
+### Pairing principles
+- **Serif-with-serif**: Arabic serif heading → Latin serif accent (Markazi Text → Fraunces)
+- **Geometric-with-geometric**: Arabic geometric heading → Latin geometric accent (Cairo → Marcellus)
+- **Never mismatched by default**: Arabic serif heading + Latin sans accent is wrong unless it's a deliberate `brand.json` override (stated in report, not silent)
+
+### Weight discipline
+- ≤ 3 families, ≤ 4 weights total across the entire page (performance budget from `memory/15-performance-budget.md`)
+- Use weight differentiation within a single family (e.g., Cairo 400 body / 700 heading) before adding a second family
+
+## Accent Faces
+
+- **`display`** token in `brand.json` — optional Latin accent face for large hero text
+- Falls back to `Cormorant Garamond` when `typography.families.display` is absent
+- **Oswald for numerals** — condensed Latin, used ONLY for spec numbers (horsepower, dimensions, pricing) inside automotive/performance builds, layered alongside the primary Arabic pair, never replacing it
+
+## Google Fonts `<link>` Reference
+
+Load only the families actually in use — never load every family in this file on every build:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=[FAMILIES]&display=swap" rel="stylesheet">
+```
+
+## Output Convention
+
+After selecting a pairing, update `brand.json`:
+```json
+"typography": {
+  "families": {
+    "heading": { "primary": "[Selected]", "fallback": "[Stack]" },
+    "body": { "primary": "[Selected]", "fallback": "[Stack]" },
+    "display": { "primary": "[Selected]", "fallback": "[Stack]" },
+    "arabicHeading": "[Selected]",
+    "arabicBody": "[Selected]"
+  }
+}
+```
+
+## Checklist
+
+- [ ] Pairing matches the mood table row, or deviation is a deliberate `brand.json` override (stated explicitly)
+- [ ] No manuscript/calligraphic face above ~24px
+- [ ] Display-only faces not used for body copy
+- [ ] `<link>` loads ONLY families actually referenced in CSS
+- [ ] ≤ 3 families, ≤ 4 weights total (performance budget)
+- [ ] Latin accent pairs intentionally with Arabic heading (serif+serif or geometric+geometric)

package/references/foundations/daisyui.md

@@ -0,0 +1,44 @@
+# Foundation: daisyUI (on Tailwind CDN)
+
+## When this is the right choice
+- Dashboards, SaaS app screens, admin panels — anything needing a large,
+  complete, accessible component set fast (tables, modals, drawers,
+  dropdowns, steps, toasts, stat cards...).
+- The prototype needs to look and behave production-grade quickly, with
+  design effort spent on the brand layer (theme, signature elements)
+  rather than on rebuilding every interactive component from scratch.
+
+## Setup (CDN, zero build)
+```html
+<script src="https://cdn.tailwindcss.com"></script>
+<link href="https://cdn.jsdelivr.net/npm/daisyui@latest/daisyui.css" rel="stylesheet" type="text/css" />
+```
+daisyUI v5 themes are CSS custom properties (OKLCH-based) — this is the one
+foundation where `tokens.css` and the component library's theme system are
+almost the same file. Define a custom `[data-theme="brand"]` block in
+`design-system/tokens.css` mapping every `brand.json` color to daisyUI's
+theme variables, then set `data-theme="brand"` on `<html>` in every page.
+
+## brand.json → daisyUI theme mapping
+`colors.primary` → `--p` (primary); `colors.light`/`colors.dark` base tones
+→ `--b1`/`--b2`/`--b3` (base surfaces); a generated neutral/accent scale →
+`--n`/`--a`. Full variable list: see the official daisyUI colors reference.
+
+## Getting exact component markup — don't guess, don't vendor a stale copy
+daisyUI publishes and maintains its own official, free, MIT-licensed skill
+covering every component's exact class names and required markup structure,
+at `https://daisyui.com/skills/daisyui/` (installable via
+`npx skills add saadeghi/daisyui`, compatible with any coding agent). When a
+component's exact daisyUI markup is needed (a `card`, a `steps` component, a
+`drawer`...), fetch the matching reference from that live source rather than
+reconstructing it from memory or from a frozen local copy — daisyUI ships
+frequent version updates and class names do change across majors.
+
+## Convention
+- `components.css` in a daisyUI project holds only project-specific
+  overrides and the signature/identity elements that shouldn't look like
+  "generic daisyUI" — never a re-implementation of something daisyUI
+  already provides.
+- Respect daisyUI's own component structure exactly (required wrapper
+  divs, ARIA attributes) — don't simplify it away for brevity; that's
+  usually what breaks the built-in accessibility/interaction behavior.

package/references/foundations/hybrid.md

@@ -0,0 +1,32 @@
+# Foundation: Hybrid (daisyUI + Native)
+
+## When this is the right choice
+The default recommendation for most real briefs: composite, "solved"
+components (tables, modals, forms, navigation, steps) don't need
+reinventing — but the handful of elements that carry the brand's actual
+personality (the hero, a signature interaction, a distinctive card variant)
+deserve hand-authored treatment so the result doesn't read as "generic
+daisyUI".
+
+## Setup
+Same CDN includes as `daisyui.md`. `components.css` loads after daisyUI's
+stylesheet so Native overrides/additions win without needing `!important`.
+
+## Division of labor
+- **daisyUI owns**: anything structurally standard — tables, modals,
+  drawers, dropdowns, form controls, pagination, toasts, steps.
+- **Native (`components.css`) owns**: the hero treatment, any signature
+  card/section variant called out during `school`, and anything the brief
+  explicitly flags as "this must not look templated".
+
+## Decision rule for `components`/`page`/`dashboard`
+Before styling anything, ask: "is this a solved, standard UI pattern, or is
+this where the brand's personality needs to show?" First → daisyUI class.
+Second → Native class in `components.css`. Never build a Native
+reimplementation of something daisyUI already solves well — that defeats
+the point of choosing Hybrid over pure Native.
+
+## brand.json mapping
+Both mappings from `daisyui.md` and `native.md` apply simultaneously — the
+daisyUI theme handles color of standard components, `tokens.css` custom
+properties handle everything Native-owned.

package/references/foundations/native.md

@@ -0,0 +1,31 @@
+# Foundation: Native (hand-authored semantic components)
+
+## When this is the right choice
+- The brief calls for a visual identity that shouldn't read as "built on a
+  known component library" — high-end brand work, a signature aesthetic.
+- Zero external dependency is a hard requirement.
+- The team downstream will hand-roll production CSS anyway, so a component
+  library choice now wouldn't survive the handoff.
+
+## Convention
+- BEM-style class naming: `.card`, `.card__title`, `.card--featured`. No
+  utility classes mixed in — layout uses `components.css`-defined layout
+  primitives (`.stack`, `.cluster`, `.grid-auto`), not ad hoc flexbox per
+  page.
+- `tokens.css` custom properties are the only source of raw values —
+  `components.css` rules reference `var(--color-primary)`,
+  `var(--space-4)`, etc., never a literal.
+- `utilities.css` stays small and layout-only (spacing/alignment helpers) —
+  resist growing it into a parallel utility framework; that's what the
+  Tailwind foundation is for.
+
+## brand.json → tokens.css mapping
+Same field set as the daisyUI/Tailwind foundations (see `tokens` command) —
+`colors.*`, `typography.*`, `spacing.*` all become `:root` custom
+properties. Native foundation is the only one with no theme-config layer in
+between — the mapping is direct.
+
+## What `components` produces here
+Hand-authored rules in `components.css`, one block per component, each
+documented with a one-line comment naming the states it supports (hover,
+active, disabled, loading).

package/references/foundations/tailwind-utility.md

@@ -0,0 +1,43 @@
+# Foundation: Tailwind Utility-First
+
+## When this is the right choice
+- Fast iteration matters more than a hand-authored component vocabulary.
+- The team downstream already works in Tailwind and will inherit these
+  classes directly into production — matches `tidyfactor-cinematic`'s own
+  CDN-only Tailwind usage, so a project can share visual language with a
+  cinematic landing page built alongside it.
+- No named component abstraction wanted — every page composed from raw
+  utilities.
+
+## Setup (CDN, zero build — same pattern as `tidyfactor-cinematic`)
+```html
+<script src="https://cdn.tailwindcss.com"></script>
+<script>
+  tailwind.config = {
+    theme: {
+      extend: {
+        colors: { /* generated from tokens.css / brand.json colors.* */ },
+        fontFamily: { /* generated from typography.families.* */ },
+        spacing: { /* generated from spacing.* if it departs from Tailwind defaults */ },
+      }
+    }
+  }
+</script>
+```
+This config block lives in one place — `design-system/` — and every page's
+`<head>` includes the same two `<script>` tags. Never redefine
+`tailwind.config` per page.
+
+## Convention
+- `components.css` still exists, but holds only the handful of patterns
+  Tailwind utilities can't express cleanly (complex pseudo-element tricks,
+  keyframe-driven states) — most pages need zero custom CSS at all.
+- No `@apply` sprawl — if a class combination repeats across 3+ pages
+  often enough to deserve a name, that's a signal to move it into
+  `components.css` as a real named class (see `components` command),
+  not to keep re-typing the utility string.
+
+## brand.json → Tailwind mapping
+`colors.*` → `theme.extend.colors`; `typography.families.*` →
+`theme.extend.fontFamily`; `spacing.*`/`radius.*`/`shadow.*` → their
+matching `theme.extend.*` keys when they depart from Tailwind's defaults.

package/references/memory/01-design-schools.md

@@ -0,0 +1,85 @@
+# Design Schools & Movements — Quick Calibration Index
+
+For complete operational rules, visual tokens, typography pairings, color systems, CSS rules, shadow styles, and anti-patterns across all 20 visual aesthetics, see:
+👉 **[`memory/16-design-movements-guide.md`](16-design-movements-guide.md)** (All 20 Visual Movements & Design Tokens)  
+👉 **[`memory/17-storytelling-industries-ux.md`](17-storytelling-industries-ux.md)** (4 Storytelling Archetypes, 8 Industry Registers, 8 UX Philosophies)  
+👉 **[`memory/18-design-decision-engine.md`](18-design-decision-engine.md)** (9-Step Decision Tree & Anti-Design-Soup Constraint)
+
+---
+
+## 🎨 20 Visual Aesthetics At-A-Glance Index
+1. **Swiss Style**: Objective 12-column grid, sans-serif, high contrast.
+2. **Flat Design**: 2D vector, zero shadows, vibrant color blocks.
+3. **Material Design**: Paper/ink depth, elevation shadows, touch ripples.
+4. **Minimalism**: Extreme negative space, typography focal point.
+5. **Brutalism & Neo-Brutalism**: Hard 4px black offset shadows, 2px borders, pop colors.
+6. **Bauhaus**: Primary color geometry (red/blue/yellow), form follows function.
+7. **Skeuomorphism**: Tactile real-world textures, inner bevels, realistic depth.
+8. **Glassmorphism**: Translucent frosted panels (`backdrop-filter: blur`), spatial layers.
+9. **Maximalism**: Collage layering, kinetic typography, energetic multi-color.
+10. **Industrial Style**: Monospaced data density, blueprint grids, telemetry dots.
+11. **Bento Box UI**: Compartmentalized modular masonry grids, `rounded-2xl` tiles.
+12. **Aurora UI**: Luminescent mesh gradients (`blur(60px)`), dark aura spotlights.
+13. **Neumorphism**: Extruded surface shadows (`inset` + drop), monochromatic grounds.
+14. **Corporate Memphis**: Friendly geometric characters, pastel panels, soft pills.
+15. **Cyberpunk & Vaporwave**: Pitch black grounds, neon cyan/magenta, monospaced HUD.
+16. **Claymorphism**: Soft 3D clay volumes, warm inner light reflections, rounded shapes.
+17. **Isometric Design**: 30° 2D parallel projection vector worlds.
+18. **Kinetic Typography**: Text as the animated hero visual (`clamp()` font scales).
+19. **Organic / Amorphous UI**: Fluid blob shapes (`border-radius: 60% 40% ...`), natural tones.
+20. **Frutiger Aero & Y2K**: Glossy glass buttons, lens flares, vibrant sky blue/lime gradients.
+
+## Bauhaus
+Geometric shapes as structural/decorative elements, primary-plus-black
+palettes, function-follows-form typography. Fits: education, design tools,
+brands wanting to signal craft/foundational thinking. Avoid: costume-party
+Bauhaus (circles+triangles as decoration with no structural logic).
+
+## Brutalism (web)
+Raw, unstyled-looking HTML elements used deliberately, harsh contrast,
+visible grid lines, monospace accents, intentionally "undesigned". Fits:
+developer tools, portfolios, brands wanting to signal authenticity/anti-
+polish. Avoid: actual unstyled defaults mistaken for the aesthetic —
+brutalism is a considered choice, not the absence of one.
+
+## Editorial / Broadsheet
+Hairline rules, dense multi-column text, serif display, byline/dateline
+conventions borrowed from print journalism. Fits: publications, long-form
+content, thought-leadership brands. Avoid: applying hairline-column density
+to a page that has nothing to say at that density (see `frontend-design`'s
+warning on this as an overused AI-design default).
+
+## Minimalism
+Extreme restraint, one accent color maximum, huge whitespace, type doing
+almost all the work. Fits: luxury, premium single-product brands. Avoid:
+minimalism as an excuse for lack of a real design decision — every
+remaining element must be precisely placed.
+
+## Glassmorphism
+Frosted-glass translucent panels, soft shadows, layered depth over a
+blurred background. Fits: modern consumer apps, dashboards wanting a soft/
+approachable data-density feel. Avoid: layering glass panels on glass
+panels — contrast and legibility break down fast.
+
+## Material-influenced
+Elevation via shadow, clear touch targets, motion as spatial logic (things
+move the way physical objects would). Fits: cross-platform app UI,
+utilitarian dashboards. Avoid: importing Material's specific component
+shapes wholesale when the brand wants its own identity — take the
+principles, not the skin.
+
+## Modern SaaS (Vercel/Linear-influenced)
+Near-black or pure-white grounds, one saturated accent, monospace for data/
+code, tight type scale, subtle gradient accents, generous but efficient
+spacing. Fits: developer tools, B2B SaaS, technical dashboards. Avoid:
+defaulting here just because the brief is "a SaaS product" — this look is
+common enough now to read as generic if the brand has no other point of
+view.
+
+## Calibration: defaults to avoid unless the brief asks for them
+Per `frontend-design`'s own calibration: warm-cream + terracotta-serif,
+near-black + single acid-green/vermilion accent, and broadsheet-hairline-
+columns applied regardless of subject are the three most common AI-design
+tells right now. Choosing one deliberately because it fits the brief is
+fine; landing on one by default is the failure mode `school` exists to
+prevent.

package/references/memory/02-design-tokens.md

@@ -0,0 +1,41 @@
+# Design Tokens — Reference for `tokens`
+
+## Categories and what belongs in each
+
+**Colors** — primary, secondary, accent; a light surface scale
+(background/surface/surface-raised) and a dark equivalent if the project
+supports both themes; semantic colors (success/warning/error/info) derived
+from the palette, not generic red/green/yellow dropped in unrelated to the
+brand.
+
+**Typography** — a display family (used with restraint, per
+`frontend-design`'s principle), a body family, optionally a mono/utility
+family for data. A type scale (e.g. a 1.25 or 1.333 ratio from a base size)
+— not arbitrary per-heading pixel values. Weight and letter-spacing as
+named tokens tied to the scale, not per-instance tweaks.
+
+**Spacing** — one consistent base unit (4px or 8px) and a small named scale
+(`--space-1` through `--space-8` or similar) — every margin/padding/gap in
+the project traces to this scale.
+
+**Radius** — a small fixed set (e.g. none/sm/md/lg/full) — resist a
+different radius value per component.
+
+**Shadow** — a small fixed elevation set (e.g. sm/md/lg), consistent light
+angle/color across all of them (usually a tint of the darkest neutral in
+the palette, not pure black).
+
+**Motion** — duration tokens (fast/base/slow) and easing tokens
+(ease-out for entrances, ease-in for exits, a signature easing curve for
+the brand's characteristic motion if `school` calls for one).
+
+## Naming convention
+`--color-*`, `--font-*`, `--space-*`, `--radius-*`, `--shadow-*`,
+`--ease-*`/`--duration-*` — consistent prefixing so any command (or a human
+reading the CSS) can immediately tell a value's category.
+
+## Contrast policy
+Every text/background pairing derived from tokens should pass WCAG AA
+(4.5:1 for body text, 3:1 for large text/UI components) — check this when
+`school` picks a direction with strong color contrast ambitions
+(near-black grounds, saturated accents), not just at the end.

package/references/memory/03-narrative-conversion.md

@@ -0,0 +1,47 @@
+# Narrative & Conversion — Reference for `page`/`dashboard`
+
+## Hero as thesis
+The opening of any page states its single job immediately — a headline, a
+demo, a number, whatever form fits the subject. Never a generic "Welcome
+to X" holding pattern. (Shared principle with `frontend-design`, applied
+here as a persistent rule across every page in the prototype, not just one.)
+
+## AIDA (Attention, Interest, Desire, Action)
+A useful ordering check for marketing pages: does the hero earn Attention
+specific to this audience? Does the next section build real Interest (not
+generic feature bullets)? Does the page build Desire before it asks for
+anything? Is the Action (CTA) singular and obvious, not competing with
+three other asks on the same screen?
+
+## StoryBrand-style framing
+The visitor is the hero of their own story, not the brand. Copy and layout
+should cast the product as the guide (the thing that helps), not the
+protagonist. A page that talks entirely about the company/product without
+naming the visitor's problem first usually reads as self-absorbed rather
+than persuasive.
+
+## Jobs-to-be-Done framing (for dashboards/app screens)
+A dashboard screen's design should answer "what job is the person here to
+do right now" before anything else — scanning for an anomaly, completing a
+task, deciding on an action. Information hierarchy follows that job, not a
+generic "show everything" density.
+
+## Structural devices carry meaning, or they don't belong
+Numbered steps, eyebrows, dividers — only use them where they encode
+something real (an actual sequence, an actual category boundary). A
+numbered "01/02/03" on three cards that aren't actually sequential is
+decoration pretending to be information — cut it or fix the content to
+actually be sequential.
+
+## Gestalt basics worth naming
+Proximity (related things grouped, unrelated things separated) and
+continuity (aligned edges read as connected) do more consistency work than
+almost any color/type decision — check these before reaching for a visual
+fix when a page "feels off".
+
+## CTA hierarchy
+One primary action per page/screen, styled as the obvious next step;
+secondary actions visually subordinate (not competing in size/color).
+Repeating the same primary CTA at natural decision points down a long page
+is a legitimate pattern — offering multiple *different* primary actions is
+not.