medesign 0.0.0-stage → 1.4.0

package/presets/tesla/design-tokens.css

@@ -0,0 +1,112 @@
+/**
+ * ME-DESIGN Preset: Tesla Cybertruck & In-Vehicle Telemetry
+ * Version: 1.0.0
+ * Architecture: 3-Layer Design Tokens (Global -> Semantic -> Component)
+ */
+
+:root {
+  /* 01. Typography */
+  --font-display: "Space Grotesk", "Inter", sans-serif;
+  --font-sans: "Inter", sans-serif;
+  --font-mono: "IBM Plex Mono", "JetBrains Mono", monospace;
+  --tracking-heading: -0.015em;
+  --tracking-badge: 0.08em;
+  --leading-ui: 1.22;
+  --leading-prose: 1.55;
+  --thai-headroom: 2px;
+
+  /* 02. Color Tokens */
+  --color-canvas: #050505;
+  --color-surface-raised: #111111;
+  --color-surface-inset: #0a0a0a;
+  --color-text-primary: #ffffff;
+  --color-text-secondary: #8e8e93;
+  --color-text-tertiary: #48484a;
+  --color-border-subtle: rgba(255, 255, 255, 0.08);
+  --color-border-strong: rgba(255, 255, 255, 0.20);
+  --color-border-focus: oklch(0.65 0.24 28);
+
+  --color-accent: oklch(0.58 0.24 28);
+  --color-accent-hover: oklch(0.64 0.24 28);
+  --color-accent-fg: #ffffff;
+
+  --color-status-info: oklch(0.78 0.15 200);
+  --color-status-success: oklch(0.72 0.20 142);
+  --color-status-warning: oklch(0.80 0.18 75);
+  --color-status-critical: oklch(0.60 0.25 28);
+
+  /* 03. Optical Geometry (Strict Low-Radius Chamfer) */
+  --radius-outer: 4px;
+  --radius-inner: 2px;
+  --hit-target-min: 44px;
+
+  /* 04. Motion Tokens (High-Velocity Precision) */
+  --duration-entry: 100ms;
+  --duration-exit: 70ms;
+  --ease-entry: cubic-bezier(0.2, 0, 0, 1);
+  --ease-exit: cubic-bezier(0.4, 0, 1, 1);
+}
+
+/* Light Mode Overrides */
+@media (prefers-color-scheme: light) {
+  :root {
+    --color-canvas: #f4f4f4;
+    --color-surface-raised: #ffffff;
+    --color-surface-inset: #e5e5e5;
+    --color-text-primary: #111111;
+    --color-text-secondary: #5c5c5c;
+    --color-border-subtle: rgba(0, 0, 0, 0.10);
+    --color-border-strong: rgba(0, 0, 0, 0.25);
+  }
+}
+
+/* Core Component Utilities */
+.tesla-panel {
+  background: var(--color-surface-raised);
+  border: 1px solid var(--color-border-subtle);
+  border-radius: var(--radius-outer);
+  padding: 16px 20px;
+  transition: border-color var(--duration-entry) var(--ease-entry);
+}
+
+.tesla-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: var(--hit-target-min);
+  padding: 0 16px;
+  border-radius: var(--radius-outer);
+  font-family: var(--font-sans);
+  font-size: 13px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: var(--tracking-badge);
+  background: var(--color-accent);
+  color: var(--color-accent-fg);
+  border: 1px solid transparent;
+  cursor: pointer;
+  outline-offset: 2px;
+  transition: background var(--duration-entry) var(--ease-entry);
+}
+
+.tesla-btn:focus-visible {
+  outline: 2px solid var(--color-border-focus);
+}
+
+.tesla-btn:active .visual-surface {
+  transform: scale(0.98);
+}
+
+.telemetry-val {
+  font-family: var(--font-mono);
+  font-variant-numeric: tabular-nums;
+  font-weight: 700;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}

package/presets/tesla/guidelines.md

@@ -0,0 +1,17 @@
+# Tesla Preset Guidelines (`/medesign tesla`)
+
+## Archetype Mapping
+- **Primary Archetype:** Archetype 18 (Industrial / Hardware Product)
+- **Secondary Archetype:** Archetype 32 (GIS Situation Awareness & Telemetry)
+
+## Invariants & Design Principles
+1. **Brutal Geometry & Minimal Radii:**
+   Outer card radius `4px`, inner nested radius `2px`. Avoid large bubbly curves; adhere to razor-sharp automotive engineering surfaces.
+2. **Telemetric Typography:**
+   - Display/Headlines: Space Grotesk / Gotham with crisp technical presence.
+   - Values & Metrics: Monospace (`IBM Plex Mono` / `JetBrains Mono`) with `tabular-nums` for real-time telemetry readouts.
+   - Letter-spacing: `+0.08em` uppercase tracking on status badges and controls.
+3. **High-Velocity Precision Motion:**
+   `precision` motion profile (100ms entry, 70ms exit). State feedback must feel immediate, like physical vehicle switches.
+4. **Contrast & Night Mode Invariant:**
+   Deep obsidian background `#050505`, crisp white metrics `#ffffff`, Tesla Crimson accent `oklch(0.58 0.24 28)` for primary action and critical warnings.

package/presets/tesla/preset.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "../schema.json",
+  "id": "tesla",
+  "name": "Tesla Cybertruck & In-Vehicle Telemetry",
+  "version": "1.0.0",
+  "archetype": "Archetype 18: Industrial / Hardware Product & Archetype 32: GIS / Telemetry",
+  "description": "Brutal hardware minimalism: razor-sharp 2px-4px chamfer radii, deep obsidian/pure black contrast, precision 90-120ms telemetry response, and electric red/cyan telemetry accents.",
+  "typography": {
+    "display": "'Gotham', 'Inter', 'Space Grotesk', sans-serif",
+    "sans": "'Inter', 'Roboto', sans-serif",
+    "mono": "'IBM Plex Mono', 'JetBrains Mono', monospace",
+    "headingTracking": "-0.015em",
+    "uiLineHeight": "1.22",
+    "proseLineHeight": "1.55",
+    "thaiHeadroom": "2px"
+  },
+  "color": {
+    "canvas": "#050505",
+    "surfaceRaised": "#111111",
+    "surfaceInset": "#0a0a0a",
+    "borderSubtle": "rgba(255, 255, 255, 0.08)",
+    "borderFocus": "oklch(0.65 0.24 28)",
+    "accent": "oklch(0.58 0.24 28)",
+    "accentForeground": "#ffffff",
+    "status": {
+      "info": "oklch(0.78 0.15 200)",
+      "success": "oklch(0.72 0.20 142)",
+      "warning": "oklch(0.80 0.18 75)",
+      "critical": "oklch(0.60 0.25 28)"
+    }
+  },
+  "geometry": {
+    "radiusBase": "2px",
+    "radiusOuter": "4px",
+    "concentricFormula": "max(0px, 4px - 1px - 2px) = 1px",
+    "scalingFormula": "clamp(0.97, 1 - 2.0/max(W, H), 0.995)",
+    "hitTargetMinTouch": "44px"
+  },
+  "motion": {
+    "profile": "precision",
+    "durationEntry": "100ms",
+    "durationExit": "70ms",
+    "easingEntry": "cubic-bezier(0.2, 0, 0, 1)",
+    "easingExit": "cubic-bezier(0.4, 0, 1, 1)"
+  },
+  "rules": [
+    "MD001_FOCUS_RING",
+    "MD002_REDUCED_MOTION",
+    "MD003_HIT_TARGET_ISOLATION",
+    "MD004_DEAD_BUTTON_CONTRACT",
+    "MD101_BENTO_ROW_FLOW"
+  ]
+}

package/references/ai-tells.md

@@ -0,0 +1,127 @@
+## 9. AI TELLS (Forbidden Patterns)
+
+Avoid these signatures unless the brief explicitly asks for them.
+
+### 9.A Visual & CSS
+* **NO neon / outer glows** by default. Use inner borders or subtle tinted shadows.
+* **NO pure black (`#000000`).** Off-black, zinc-950, or charcoal.
+* **NO oversaturated accents.** Desaturate to blend with neutrals.
+* **NO excessive gradient text** for large headers.
+* **NO custom mouse cursors.** Outdated, accessibility-hostile, perf-hostile.
+
+### 9.B Typography
+* **AVOID Inter as default.** See Section 4.1. Override path exists.
+* **NO oversized H1s** that just scream. Control hierarchy with weight + color, not raw scale.
+* **Serif constraints:** Serif for editorial / luxury / publication. Not for dashboards.
+
+### 9.C Layout & Spacing
+* **Mathematically perfect** padding and margins. No floating elements with awkward gaps.
+* **NO 3-column equal feature cards.** The generic "three identical cards horizontally" feature row is banned. Use 2-column zig-zag, asymmetric grid, scroll-pinned, or horizontal-scroll alternative.
+
+### 9.D Content & Data ("Jane Doe" Effect)
+* **NO generic names.** "John Doe", "Sarah Chan", "Jack Su" → use creative, realistic, locale-appropriate names.
+* **NO generic avatars.** No SVG "egg" or Lucide user icons → use believable photo placeholders or specific styling.
+* **NO fake-perfect numbers.** Avoid `99.99%`, `50%`, `1234567`. Use organic, messy data (`47.2%`, `+1 (312) 847-1928`).
+* **NO startup-slop brand names.** "Acme", "Nexus", "SmartFlow", "Cloudly" → invent contextual, premium names that sound real.
+* **NO filler verbs.** "Elevate", "Seamless", "Unleash", "Next-Gen", "Revolutionize" → concrete verbs only.
+
+### 9.E External Resources & Components
+* **NO hand-rolled SVG icons.** Use Phosphor / HugeIcons / Radix / Tabler. Lucide on explicit request only.
+* **Hand-rolled decorative SVGs strongly discouraged** as default (see Section 4.8).
+* **NO div-based fake screenshots.** Never build a fake product UI out of `<div>` rectangles to simulate a screenshot. Use real images, generated images, or skip the preview.
+* **NO broken Unsplash links.** Use `https://picsum.photos/seed/{descriptive-string}/{w}/{h}`, or generated photo placeholders, or actual assets.
+* **shadcn/ui customization:** Allowed, but NEVER in default state. Customize radii, colors, shadows, typography to the project aesthetic.
+* **Production-Ready Cleanliness:** Code visually clean, memorable, meticulously refined.
+
+### 9.F Production-Test Tells (banned outright)
+
+These patterns came out of real LLM-generated landing-page tests. They are the signatures the model defaults to when it tries to "look designed." Treat them as hard bans unless the brief explicitly calls for one.
+
+**Hero & top-of-page**
+* **NO version labels in the hero.** `V0.6`, `v2.0`, `BETA`, `INVITE-ONLY PREVIEW`, `EARLY ACCESS`, `ALPHA` - banned as default eyebrows. Only acceptable when the brief is explicitly about a product launch / preview status.
+* **NO "Brand · No. 01"-style sub-eyebrows.** "Marrow · No. 01 · The 6-quart" type micro-meta lines. Skip them.
+
+**Section numbering & micro-labels**
+* **NO section-number eyebrows.** `00 / INDEX`, `001 · Capabilities`, `002 · Featured commission`, `06 · how it works`, `05 · The honest table` - banned. Eyebrows should name the topic in plain language, not enumerate.
+* **NO `01 / 4`-style pagination on images or bento tiles.** If the user can count, they don't need the label.
+* **NO `Scroll · 001 Capabilities`-style scroll cues.** A simple arrow or "Scroll" is enough; no section-number prefix.
+* **NO "Index of Work, 2018 - 2026"-style range labels** as eyebrows. Just say what the section is.
+
+**Separators & dots**
+* **The middle-dot (`·`) is rationed.** Maximum 1 per line in metadata strips. Do NOT use it as the default separator for everything ("foo · bar · baz · qux · quux"). If you need a separator family, prefer line breaks, hairlines, or columns.
+* **NO decorative colored status dots on every list/nav/badge.** A colored dot before "ONE Q4 SLOT OPEN" or before every nav link, or every task row - banned by default. Acceptable only when the dot conveys actual semantic state (a server status, an availability flag) and is used sparingly.
+
+**Em-dashes & typography flourishes**
+* **NO em-dash (`—`) as a design element OR anywhere else.** See Section 9.G below for the complete, non-negotiable ban. The em-dash character is forbidden in headlines, eyebrows, pills, body copy, quotes, attribution, captions, button text, and alt text. Use the regular hyphen (`-`).
+* **NO `<br>`-broken-and-italicized headlines** as a default "design move." "for thirty\<br\>*years.*" type splits. Headlines should read naturally first, get clever only when the brief demands it.
+* **NO vertical rotated text** ("INDEX OF WORK, 2018 - 2026" rotated 90°). Agency-portfolio cliché. Use it only when the brief is explicitly agency / Awwwards / experimental AND it serves a real composition purpose.
+* **NO crosshair / hairline grid lines as decoration.** Vertical and horizontal lines drawn just to make the page "feel designed" - banned. Use them only when they organize real content.
+
+**Fake product previews**
+* **NO div-based fake product UI in the hero** (fake task list, fake terminal, fake dashboard built from styled divs). It is the #1 LLM-design Tell. Use a real screenshot, a generated image, a real component preview, or none at all.
+* **NO fake version footers** ("v0.6.2-rc.1", "last sync 4s ago · main") inside fake screenshots. Adds nothing, screams AI.
+
+**Marketing-copy Tells**
+* **NO "Quietly in use at" / "Quietly trusted by"** social-proof headers. Use natural language: "Trusted by", "Used at", "Customers include", or skip the heading entirely if the logos speak.
+* **NO "From the field" / "Field notes" / "Currently on the bench" / "On our desks" / "Loose plates" style poetic labels** on quote, blog, or sidebar sections. Reads as performative-craftsman. Use plain functional labels ("Testimonials", "Latest writing", "Now working on") or skip the label.
+* **NO "We respect the French ones"-style** mock-humble industry-references in body copy. Cute and AI-y.
+* **NO weather / locale strips** ("LIS 14:23 · 18°C") in headers/footers unless the brief is explicitly about a place / time-zone-distributed studio.
+* **NO micro-meta-sentences under eyebrows.** Sentences like *"Each of these is a feature we ship today, not a roadmap promise. The list will stay short on purpose."* sitting under a section heading are clutter. Eyebrow + Headline + Body is enough.
+* **NO generic step labels.** "Stage 1 / Stage 2 / Stage 3", "Step 1 / Step 2 / Step 3", "Phase 01 / Phase 02 / Phase 03", "Pass One / Pass Two / Pass Three". Banned. The actual step content is the label. If you must show progression, use the verb-noun directly ("Install", "Configure", "Ship") not "Stage 1: Install".
+
+**Pills, labels and version stamps**
+* **NO pills/labels/tags overlaid on images.** No `<span>` overlays on photos with tags like `Brand · 02`, `PLATE · BRAND`, `Field notes - journal`. Either let the image speak alone, or add a caption directly below (outside the image).
+* **NO photo-credit captions as decoration.** Strings like `Field study no. 12 · Ines Caetano`, `Plate 03 · House archive`, `Frame XII · 35mm` under stock/picsum images are pretentious. Photo credit is allowed ONLY when there is a real photographer being credited for a real photo (with permission). Otherwise: skip the caption or use a one-line functional caption ("The 6-quart, in Sage.").
+* **NO version footers on marketing pages.** Footer strings like `v1.4.2`, `Build 0048`, `last sync 4s ago · main` are CLI / devtool fixtures, not landing-page content. Banned on marketing/landing/portfolio pages.
+* **NO "Reservation 412 of 800"-style live-stock counters** as decoration. Only if the brief is explicitly a limited-run waitlist with real data.
+
+**Decoration text strips**
+* **NO decoration text strip at hero bottom.** Patterns like `BRAND. MOTION. SPATIAL.`, `TYPE / FORM / MOTION`, `DESIGN · BUILD · SHIP`, `ESTD. 2018 · LISBON · BRAND. MOTION. SPATIAL.` as a small mono-caps strip across the bottom of the hero are an agency-portfolio cliché. Banned by default. Only acceptable when the strip carries real, navigable links (sticky bottom nav) or real status info (cookie banner, build info on a docs site).
+* **NO floating top-right sub-text in section headings.** Pattern: section has a giant left-aligned headline; in the top-right corner of the same section header there is a small explainer paragraph floating with no clear alignment to anything else. That floater is the Tell. Either put the sub-text directly under the headline, or build a clean 2-column header (left: headline, right: aligned body), but not a tiny corner paragraph.
+
+**Lists, dividers and scoring**
+* **NO `border-t` + `border-b` on every row of a long list / spec table.** Pick one (bottom-border between rows OR top-border above the group) and use it sparsely. A 10-row spec table with hairlines under each row is the laziest layout - see Section 4.9 for alternative UI components.
+* **NO scoring/progress bars with filled background tracks** as comparison visuals. If you need to show "X out of Y" comparisons, prefer a number + small icon, or a tiny inline bar WITHOUT a background track. Big filled `bg-zinc-200` tracks with a partial fill on top are dashboard-UI clutter on a landing page.
+
+**Locale, time, scroll cues**
+* **Locale / city-name / time / weather strips are banned for 99% of briefs.** "Lisbon, working with founders" in the hero, "1200-690 Lisbon, Portugal" in the footer, "Lisbon 14:23 · 18°C" in the nav. These are agency-portfolio decoration tells. Allowed ONLY when: the brief explicitly describes a globally-distributed studio with timezone-relevant work, OR a travel-focused brand, OR a real-world physical venue. A single contact-address mention in the footer is fine; an atmospheric locale strip is not.
+* **Scroll cues are banned.** `Scroll`, `↓ scroll`, `Scroll to explore`, `Scroll to walk through it`, animated mouse-wheel icons. If the user has not scrolled yet, they are looking at the hero. They know what scroll is. The bottom of the viewport does not need a label.
+* **ZERO decorative status dots by default.** A coloured dot before nav items, before list rows, before badges, before status labels is a Tell. Only acceptable when conveying real semantic state (a live indicator on actual server status, a live availability flag) and limited to one per page section.
+
+### 9.G EM-DASH BAN (the single most-violated Tell)
+
+**Em-dash (`—`) is COMPLETELY banned.** It is the LLM's signature stylistic crutch and it is the #1 visual Tell in production tests. There is no "limited use" allowance, no "natural language frequency" allowance, no "in body copy is fine" allowance. None.
+
+* **Banned in headlines.** Use a period or a comma.
+* **Banned in eyebrows / labels / pills / button text / image captions / nav items.** Replace with line breaks, columns, or hairlines.
+* **Banned in body copy.** Restructure the sentence: two sentences with a period, OR a comma, OR parentheses, OR a colon.
+* **Banned in quote attribution.** Use a normal hyphen with spaces (` - `) or a line break + smaller-weight name.
+* **Banned in en-dash form too (`–`) when used as a separator.** Date ranges (`2018-2026`) use a hyphen. Number ranges (`€40-80k`) use a hyphen.
+
+The ONLY permitted dash characters on the page are:
+* Regular hyphen `-` (for compound words, ranges, line dividers in markup)
+* Minus sign in math (`-5°C`)
+
+If your output contains a single `—` or `–` anywhere visible to the user, the output fails the Pre-Flight Check and must be rewritten.
+
+This rule is non-negotiable. The agent has historically ignored em-dash limits when phrased as "use sparingly." The phrasing here is binary: zero em-dashes.
+
+Scope: text rendered in the UI being built; does not apply to chat replies or skill metadata.
+
+---
+
+
+### 9.H Structural, IA & Interaction Slop (Decisionless Uniformity)
+
+การป้องกัน AI Slop ที่แท้จริงต้องก้าวข้ามการห้ามแค่สไตล์ผิวเผิน ไปสู่การสกัดกั้น **"ความสม่ำเสมอที่ไร้การตัดสินใจ" (Decisionless Uniformity)**:
+
+1. **Structural & Layout Slop:**
+   - **NO Equal-Weight Metric Uniformity:** ห้ามทำ Dashboard ที่แจกแจงการ์ดขนาดเท่ากัน 4-6 ใบโดยไม่ระบุว่าตัวเลขใดคือ Primary Decision Metric และตัวเลขใดคือ Secondary Context
+   - **NO Unjustified Table-to-Card Conversion:** ห้ามแปลงตารางข้อมูลเชิงวิเคราะห์/พิกัด/ราคา ให้เป็นการ์ดสี่เหลี่ยมเรียงต่อกัน หากการแปลงนั้นทำให้ผู้ใช้สูญเสียความสามารถในการสแกนเปรียบเทียบค่าทางสายตา (Visual Row Scanning)
+   - **NO Workflow-Agnostic Responsive Stacking:** บนมือถือ ห้ามแค่สั่ง `grid-cols-1` ทื่อๆ โดยไม่จัดลำดับความสำคัญใหม่ หน้าทำงานระดับวิศวกรรมต้องตรึงเครื่องมือหลักและแผนที่/กราฟไว้ด้านบนเสมอ
+
+2. **Interaction Slop (Dead Feedback):**
+   - **NO Cosmetic Hover on Static Elements:** ห้ามใส่ `hover:-translate-y-1` หรือ Hover Glow บนการ์ดที่คลิกไม่ได้และไม่มี Navigation Link
+   - **NO Broken State Contract:** ทุกปุ่มต้องมีสถานะครบ 6 ชั้น (`default → hover → pressed → focus-visible → disabled/loading → success/error`) ห้ามมีปุ่มที่กดแล้วนิ่งสนิท
+   - **NO Accent Color Inflation:** สีเน้น (Accent Color) ต้องใช้ไม่เกิน 10-15% ของพื้นที่หน้าจอทั้งหมด ห้ามระบายสีเน้นลงบนไอคอน หัวข้อ และการ์ดทุกใบจนปุ่ม CTA สูญเสียแรงดึงดูดสายตา (Visual Gravity)
+

package/references/appendices.md

@@ -0,0 +1,220 @@
+## Appendix A - Install Commands per Design System
+
+```bash
+# Material Web (Material 3)
+npm install @material/web
+
+# Fluent UI React (v9)
+npm install @fluentui/react-components
+
+# Fluent UI Web Components (framework-free)
+npm install @fluentui/web-components @fluentui/tokens
+
+# IBM Carbon
+npm install @carbon/react @carbon/styles
+
+# Radix Themes
+npm install @radix-ui/themes
+
+# shadcn/ui (open code, owned components)
+npx shadcn@latest init
+npx shadcn@latest add button card badge separator input
+
+# Primer CSS (GitHub product/devtool UI)
+npm install --save @primer/css
+
+# Primer Brand (GitHub marketing UI)
+npm install @primer/react-brand
+
+# GOV.UK Frontend
+npm install govuk-frontend
+
+# USWDS (US Web Design System)
+npm install uswds
+
+# Atlassian Design System (Atlaskit)
+yarn add @atlaskit/css-reset @atlaskit/tokens @atlaskit/button @atlaskit/badge @atlaskit/section-message @atlaskit/card
+
+# Bootstrap 5.3
+npm install bootstrap
+
+# Shopify Polaris Web Components (Shopify apps only)
+# Add this to your app HTML head:
+#   <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
+#   <script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>
+```
+
+## Appendix B - Canonical Sources (read these before reinventing)
+
+### Material Web
+- https://github.com/material-components/material-web
+- https://material-web.dev/theming/material-theming/
+- https://m3.material.io/develop/web
+
+### Fluent UI
+- https://fluent2.microsoft.design/get-started/develop
+- https://fluent2.microsoft.design/components/web/react/
+- https://github.com/microsoft/fluentui
+- https://learn.microsoft.com/en-us/fluent-ui/web-components/
+
+### Carbon
+- https://carbondesignsystem.com/
+- https://github.com/carbon-design-system/carbon
+- https://carbondesignsystem.com/developing/react-tutorial/overview/
+- https://carbondesignsystem.com/developing/web-components-tutorial/overview/
+
+### Shopify Polaris
+- https://shopify.dev/docs/api/app-home/web-components
+- https://github.com/Shopify/polaris-react
+- https://polaris-react.shopify.com/components
+
+### Atlassian
+- https://atlassian.design/get-started/develop
+- https://atlassian.design/components/button/examples
+- https://atlaskit.atlassian.com/packages/design-system/button/example/disabled
+- https://atlassian.design/tokens/design-tokens
+
+### Primer
+- https://primer.style/
+- https://github.com/primer/css
+- https://github.com/primer/brand
+
+### GOV.UK
+- https://design-system.service.gov.uk/components/button/
+- https://design-system.service.gov.uk/styles/layout/
+- https://github.com/alphagov/govuk-frontend
+
+### USWDS
+- https://designsystem.digital.gov/documentation/developers/
+- https://designsystem.digital.gov/components/button/
+- https://designsystem.digital.gov/components/card/
+- https://github.com/uswds/uswds
+
+### Bootstrap
+- https://getbootstrap.com/docs/5.3/layout/grid/
+- https://getbootstrap.com/docs/5.3/components/card/
+
+### Tailwind
+- https://tailwindcss.com/docs/dark-mode
+- https://tailwindcss.com/blog/tailwindcss-v4
+
+### Radix
+- https://www.radix-ui.com/themes/docs/components/theme
+- https://www.radix-ui.com/themes/docs/components/card
+- https://github.com/radix-ui/themes
+
+### shadcn/ui
+- https://ui.shadcn.com/docs
+- https://ui.shadcn.com/docs/components/card
+- https://github.com/shadcn-ui/ui
+
+### Native CSS / W3C standards
+- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/backdrop-filter
+- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-color-scheme
+- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion
+- https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout
+- https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Scroll-driven_animations
+- https://drafts.csswg.org/scroll-animations-1/
+
+### Apple Liquid Glass (Apple platforms only)
+- https://developer.apple.com/design/human-interface-guidelines/materials
+- https://developer.apple.com/documentation/TechnologyOverviews/liquid-glass
+- https://developer.apple.com/documentation/TechnologyOverviews/adopting-liquid-glass
+- https://developer.apple.com/documentation/SwiftUI/Material
+
+---
+
+## Appendix C - Apple Liquid Glass: Honest Web Approximation
+
+Do **not** treat random CSS snippets as official Apple Liquid Glass.
+
+### What is official
+Apple documents Liquid Glass inside Apple's Human Interface Guidelines and Developer Documentation for **Apple platforms**. It is a dynamic material used across Apple platform UI. Apple's native implementation belongs to Apple platform APIs and system components, **not a public web CSS package**.
+
+Relevant official docs:
+- Apple Human Interface Guidelines → Materials
+- Apple Developer Documentation → Liquid Glass
+- Apple Developer Documentation → Adopting Liquid Glass
+- SwiftUI → Material
+
+### What is NOT official
+There is no `liquid-glass.css` from Apple for normal websites.
+
+A web approximation can use:
+- `backdrop-filter`
+- transparent backgrounds
+- layered borders
+- highlight overlays
+- gradients
+- motion
+- strong contrast fallbacks
+
+But that is **web glassmorphism / frosted-glass approximation**, not official Apple Liquid Glass. Label it as such in comments.
+
+### Safer web approximation skeleton
+
+```css
+.liquid-glass-web-approx {
+  position: relative;
+  isolation: isolate;
+  overflow: hidden;
+  border-radius: 999px;
+  border: 1px solid rgb(255 255 255 / .32);
+  background:
+    linear-gradient(135deg, rgb(255 255 255 / .30), rgb(255 255 255 / .08)),
+    rgb(255 255 255 / .12);
+  backdrop-filter: blur(24px) saturate(180%) contrast(1.05);
+  -webkit-backdrop-filter: blur(24px) saturate(180%) contrast(1.05);
+  box-shadow:
+    inset 0 1px 0 rgb(255 255 255 / .48),
+    inset 0 -1px 0 rgb(255 255 255 / .12),
+    0 18px 60px rgb(0 0 0 / .18);
+}
+
+.liquid-glass-web-approx::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  border-radius: inherit;
+  background:
+    radial-gradient(circle at 20% 0%, rgb(255 255 255 / .55), transparent 34%),
+    linear-gradient(90deg, rgb(255 255 255 / .18), transparent 42%, rgb(255 255 255 / .14));
+  pointer-events: none;
+}
+
+.liquid-glass-web-approx::after {
+  content: "";
+  position: absolute;
+  inset: 1px;
+  border-radius: inherit;
+  border: 1px solid rgb(255 255 255 / .14);
+  pointer-events: none;
+}
+
+@media (prefers-color-scheme: dark) {
+  .liquid-glass-web-approx {
+    border-color: rgb(255 255 255 / .18);
+    background:
+      linear-gradient(135deg, rgb(255 255 255 / .16), rgb(255 255 255 / .04)),
+      rgb(15 23 42 / .42);
+    box-shadow:
+      inset 0 1px 0 rgb(255 255 255 / .22),
+      0 18px 60px rgb(0 0 0 / .42);
+  }
+}
+
+@media (prefers-reduced-transparency: reduce) {
+  .liquid-glass-web-approx {
+    background: rgb(255 255 255 / .96);
+    backdrop-filter: none;
+    -webkit-backdrop-filter: none;
+  }
+}
+```
+
+**Important:** `prefers-reduced-transparency` has uneven browser support; test it. Always provide enough contrast even without blur.
+
+---
+
+**End of appendices.** Install commands above are reality anchors. The Apple Liquid Glass skeleton is a labeled approximation, not an Apple-issued package. For canonical docs per design system, consult the system's official docs (links in Section 2 plus Appendix B).

package/references/architecture.md

@@ -0,0 +1,39 @@
+## 3. DEFAULT ARCHITECTURE & CONVENTIONS
+
+Unless the design read picks a real design system (Section 2.A), these are the defaults:
+
+### 3.A Stack
+* **Framework:** React or Next.js. Default to Server Components (RSC).
+  * **RSC SAFETY:** Global state works ONLY in Client Components. In Next.js, wrap providers in a `"use client"` component.
+  * **INTERACTIVITY ISOLATION:** Any component using Motion, scroll listeners, or pointer physics MUST be an isolated leaf with `'use client'` at the top. Server Components render static layouts only.
+* **Styling:** **Tailwind v4** (default). Tailwind v3 only if the existing project demands it.
+  * For v4: do NOT use `tailwindcss` plugin in `postcss.config.js`. Use `@tailwindcss/postcss` or the Vite plugin.
+* **Animation:** **Motion** (the library formerly known as Framer Motion). Import from `motion/react` (`import { motion } from "motion/react"`). The `framer-motion` package still works as a legacy alias - prefer `motion/react` in new code.
+* **Fonts:** Always use `next/font` (Next.js) or self-host with `@font-face` + `font-display: swap`. Never link Google Fonts via `<link>` in production.
+
+### 3.B State
+* Local `useState` / `useReducer` for isolated UI.
+* Global state ONLY for deep prop-drilling avoidance - Zustand, Jotai, or React context.
+* **NEVER** use `useState` to track continuous values driven by user input (mouse position, scroll progress, pointer physics, magnetic hover). Use Motion's `useMotionValue` / `useTransform` / `useScroll`. `useState` re-renders the React tree on every change and collapses on mobile.
+
+### 3.C Icons
+* **Allowed libraries (priority order):** `@phosphor-icons/react`, `hugeicons-react`, `@radix-ui/react-icons`, `@tabler/icons-react`.
+* **Discouraged:** `lucide-react`. Acceptable only when the user explicitly asks for it or the project already depends on it.
+* **NEVER hand-roll SVG icons.** If a glyph is missing, install a second library or compose from primitives - do not draw icon paths from scratch.
+* **One family per project.** Do not mix Phosphor with Lucide in the same component tree.
+* **Standardize `strokeWidth` globally** (e.g. `1.5` or `2.0`).
+
+### 3.D Emoji Policy
+Discouraged by default in code, markup, and visible text. Replace symbols with icon-library glyphs. **Override:** allow emojis only when the user explicitly asks for a playful / chat-style / social-native vibe - and even then use them sparingly with intent.
+
+### 3.E Responsiveness & Layout Mechanics
+* Standardize breakpoints (`sm 640`, `md 768`, `lg 1024`, `xl 1280`, `2xl 1536`).
+* Contain page layouts using `max-w-[1400px] mx-auto` or `max-w-7xl`.
+* **Viewport Stability:** NEVER use `h-screen` for full-height Hero sections. ALWAYS use `min-h-[100dvh]` to prevent layout jumping on mobile (iOS Safari address bar).
+* **Grid over Flex-Math:** NEVER use complex flexbox percentage math (`w-[calc(33%-1rem)]`). ALWAYS use CSS Grid (`grid grid-cols-1 md:grid-cols-3 gap-6`).
+
+### 3.F Dependency Verification (mandatory)
+Before importing ANY 3rd-party library, check `package.json`. If the package is missing, output the install command first. **Never** assume a library exists.
+
+---
+