design

name	design
user-invocable	false
description	Design philosophy for adaptive, spatial interfaces. Paradigm selection, material language, interaction patterns, inclusive design, ecosystem thinking, and progressive immersion strategy. Use for design direction, visual language decisions, and spatial UI planning.
token_version	2.5.0

Design Skill

Design philosophy and visual direction for building spatial-ready, AI-driven interfaces. This skill shapes what to build and why — implementation.md covers how (tooling, tokens, compliance).

Paradigm: The Adaptive Surface. Aesthetic direction: Warm Earth — architectural warmth, handmade precision, garden journal over trading terminal (see root DESIGN.md). Design language: the Warm Earth language — Material 3 Expressive × Liquid Glass structural precision. Content-forward hierarchy, concentric geometry, spring physics, organic color. Root DESIGN.md front matter is the canonical DesignMD token source; see language.md for implementation guidance.

Route to another skill when…

• You need an at-a-glance map of this skill stack (which file owns which question) → ARCHITECTURE.md.
• You need implementation detail (Tailwind tokens, Radix composition, a11y checks, Storybook, i18n) → implementation.md.
• You are about to feed a design to an AI tool or coding agent → ai-ui-brief.md + § Working with AI Design Tools below + the matching prompt contract.
• You need the admin AI prompt contract (stable core, vocabulary, never-use list) → prompt-contract.md.
• You need the client AI prompt contract → client-prompt-contract.md.
• You need to report a UI defect on an admin surface (grammar, component identifiers, browser workflow) → defect-grammar.md.
• You just need a scannable token cheat sheet → quick-reference.md.
• You are doing a full design-system alignment review across DesignMD files, tokens, Storybook, admin, client, docs, and agentic guidance → system-alignment-review.md. Use stack-review.md instead when the target is only the design/ skill stack.

Token version

This skill's frontmatter token_version reflects the current Warm Earth token spec in language.md; scripts/design/check-tokens.sh requires the field and verifies every spec'd token is projected into theme.css.

When language.md tokens change (radii, springs, materials, color roles): bump token_version here and re-verify implementation.md references still align.

Activation

Domain	Keywords / Triggers	Sub-file
Skill Map	where does X live, skill stack, routing, architecture overview	ARCHITECTURE.md
Design Language	Warm Earth language, shape system, motion tokens, color direction, components, hero moments	language.md
AI UI Brief	reusable prompt contract, external reference role map, saved UI/CSS build brief	ai-ui-brief.md
Admin Prompt Contract	admin stable core, banned terms, workspace vocabulary for AI design tools	prompt-contract.md
Client Prompt Contract	client stable core, banned terms, PWA shell vocabulary	client-prompt-contract.md
Defect Grammar	"this looks broken", describe UI bug, component identifier lookup, defect types, browser inspect workflow	defect-grammar.md
Quick Reference	cheat sheet, radii, springs, colors, materials, paradigms at a glance	quick-reference.md
Design Philosophy	design direction, paradigm, adaptive surface, spatial, vision, progressive immersion	This file
Depth & Space	Z-axis, depth, layers, glass pane, elevation, scroll depth	spatial.md
Interaction	adaptive density, progressive disclosure, multimodal, hover-to-gaze	interaction.md
Materials	glass, material, blur, surface, frosted, translucent	materials.md
Generative UI	UI atoms, intent-driven composition, agent-generated surfaces	generative-ui.md
View Transitions	view transition API, entity morphing, spatial navigation	implementation.md § View Transitions
Ecosystem	ecosystem, relational, cascade, multi-user, surrogate, autonomic, archetype	ecosystem.md
Regenerative	regenerative, regen, degen, mycofi, commons, biomimicry, succession, growth-agnostic, capability	regenerative.md
Review Checklist	review, PR, audit, compliance, checklist, design review, before merging	review-checklist.md
Stack Review	stack review, audit skill stack, meta-review, design skill stack health	stack-review.md
System Alignment Review	design system alignment, design-system alignment, UI drift, Storybook alignment, admin client docs alignment, full repo design-system review	system-alignment-review.md
Inspiration & Frameworks	inspiration, design books, designers, studios, research	§ Appendix below

When invoked:

1. Establish design paradigm and material metaphor before writing code
2. Apply Inclusive Design lens — every decision raises or lowers barriers
3. Apply Ecosystem lens for multi-user surfaces — whose experience composes with whose? (ecosystem.md)
4. Defer to implementation.md for TailwindCSS config, Radix primitives, Storybook, i18n, compliance
5. Run the unified review-checklist.md (4 lenses: Regenerative / Spatial / Ecosystem / Compliance) on new components before merging

---

Quad Foundation

Four frameworks anchor every design decision:

The Adaptive Surface Paradigm

The interface is a set of adaptive surfaces. Information floats in layers of relevance — the most urgent at eye level, the contextual at the periphery, the archival behind a gesture. Controls appear when context demands them and recede when it doesn't. The user is in command, not along for the ride.

This paradigm is not decoration. It is information architecture expressed through depth, density, and contextual revelation. A dashboard that shows everything at once has every surface at maximum opacity — it creates noise, not awareness.

Not everything should be spatial. A simple form is a simple form. The paradigm applies when: the user monitors multiple data streams, a primary focus needs auxiliary context, or the interface is dense enough to benefit from depth layering.

Microsoft Inclusive Design

Three principles woven throughout — not a checklist, a lens:

• Recognize Exclusion — Spatial interfaces create new forms of exclusion: gorilla arm fatigue, gaze tracking imprecision, depth perception variance, motion sickness. The Persona Spectrum maps these across permanent, temporary, and situational contexts.
• Learn from Diversity — Adaptive density and progressive disclosure serve cognitive diversity, not just preference. The Cognition Extension adds: understand motivation → discern cognitive load → co-create across the neurodiversity spectrum.
• Solve for One, Extend to Many — Every spatial pattern must degrade gracefully to 2D, voice, and keyboard. Closed captions started for the deaf and became universal. Spatial patterns that work only in spatial mode are incomplete.

Regenerative Design

Does this design regenerate or extract? Seven principles — make the mycelium visible, design for succession, enrich the edges, failure is succession, be growth-agnostic, capability is the deliverable, regen not degen. Full framework: regenerative.md. PR checks live in the unified review-checklist.md § Lens 1.

User Ecosystem Thinking

The interface exists in an ecosystem of interconnected people. A single design decision cascades across users who may never see the same screen. Based on Youngblood, Chesluk, and Haidary's framework (BIS Publishers, 2021).

• Design for relationships, not individuals — 15 archetypes classify users by their functional relationship to the artifact (Direct, Governing, Dependent, Autonomic, etc.), not by demographics. A person occupies multiple archetypes simultaneously.
• Make cascades visible — When a governing user's action affects dependent users, show the blast radius before confirmation. "Reject" is not just a button — it is a decision that reaches Maria.
• Surface autonomic actors — On-chain contracts, indexers, and resolvers are not infrastructure. They are non-human actors whose behavior shapes every user's experience. Give them visible state.

Full framework, Green Goods ecosystem map, and design patterns: ecosystem.md

---

Paradigm Selection

Choose one paradigm per surface. Mix across a view.

Paradigm	When	Feel	Density
Command Surface	Primary action area	Glass pane, sharp focus, high contrast	High — controls visible and ready
Ambient Display	Status, background info	Translucent, soft, peripheral	Low — glanceable, never demands attention
Data Landscape	Analytics, history, flows	Volumetric, layered, navigable	Variable — zooms overview to detail
Conversational	AI interaction, guidance	Minimal chrome, content-forward	Sparse — message and response
Ritual	Onboarding, confirmation, ceremony	Full-screen, cinematic, focused	Single-purpose — one thing, done well

Material Metaphors

Pick a material that carries the entire surface:

Material	Visual Language	Best For
Liquid Glass	Refracted light, variable blur, chromatic edges	Command surfaces, active workspaces (default material for client PWA)
Obsidian	Dark, reflective, warm accent glows on interaction	Data landscapes, operator tools
Vellum	Warm, tactile, paper-like grain texture	Conversational surfaces, documentation
Holographic	Iridescent edges, gradient shifts, spectral accents	Ritual moments, celebrations, onboarding
Carbon	Industrial matte dark, precise grid lines, monospace	Technical/operator surfaces, config

Then enforce it — every element speaks the same material language.

Admin Cockpit Carve-Out

For packages/admin and operator dashboards, do not treat the Warm Earth language as permission to make the cockpit theatrical. The cockpit inherits warmth and concentric geometry from the design language, but expresses them through restraint — solid surfaces, quiet workspace tint, utility copy. See prompt-contract.md for the stable admin brief.

• Default to Command Surface with restrained material, strong typography, and calm workspace hierarchy.
• Use subtle atmosphere and tint, not decorative spectacle.
• Prefer utility copy, visible task flow, and inspector patterns over immersive scenes or brand moments.
• If a design move would be inappropriate for Linear, GitHub, or Stripe Dashboard, it is probably inappropriate for Green Goods admin unless explicitly requested.

---

Working with AI Design Tools

The platforms come and go. The contract is platform-agnostic and saved in ai-ui-brief.md:

1. Feed the right context — ai-ui-brief.md + root DESIGN.md + the matching surface DESIGN.md (packages/admin/DESIGN.md, packages/client/DESIGN.pwa.md, packages/client/DESIGN.browser.md, or docs/DESIGN.md) + the matching prompt contract when one exists (prompt-contract.md admin / client-prompt-contract.md client).
2. One screen per pass — quality degrades when multiple screens get bundled into a single prompt.
3. Screenshot is the source of truth — generated HTML is reference only. Map output back to existing components; never accept generic React.
4. Use the canonical palette — Admin* wrappers (admin) or @green-goods/shared primitives (client). Flag missing primitives instead of inventing component names.
5. Route by repo-owned sources — use ARCHITECTURE.md, the surface DESIGN file, and the matching prompt contract as the surface map.

If a platform-specific quirk really is worth recording (e.g. a one-line tip about a particular tool's prompt parser), put it in your user memory, not in a project skill. Project skills outlive any single tool.

---

Anti-Patterns

Design Philosophy

1. Dashboard-itis — Cramming every metric onto one flat surface. Use progressive disclosure.
2. Spatial for spatial's sake — A contact form doesn't need depth layers. Match paradigm to complexity.
3. Glass without purpose — Blurring everything ≠ depth. Materials serve information hierarchy.
4. Edge-anchored in 2026 — Anchoring nav to viewport edges. In spatial computing, there are no edges. Float controls.
5. Uniform density — Same spacing everywhere. Adapt: comfortable / compact / focused.

Inclusive Design

6. Spatial-only patterns — Any interaction that requires gaze, gesture, or depth perception without keyboard/voice fallback.
7. Cognitive overload via material — Ultrathin glass over text-dense content. Thick material is mandatory for readability.
8. Motion without escape — Spatial animations without prefers-reduced-motion respect.
9. Assuming full vision — Depth cues that rely solely on blur or parallax without alternative hierarchy signals (size, weight, contrast).

Visual Execution

10. Generic AI slop — Inter + purple gradient + white bg + predictable grid = forgettable.
11. Sharp corners at scale — Squircles for panes. Sharp only for inline text elements.
12. Motion without meaning — Every animation communicates state change, not decoration.
13. Client styling in the cockpit — Do not import landing-page or public-brand composition rules into operator surfaces.

---

Decision Tree

What kind of design work?
│
├─► New view or page?
│   ├── Choose paradigm (Command / Ambient / Data / Conversational / Ritual)
│   ├── Choose material metaphor (Glass / Obsidian / Vellum / Holographic / Carbon)
│   ├── Apply Inclusive Design lens (who gets excluded? what's the fallback?)
│   ├── Define disclosure layers (glance → scan → engage → deep dive)
│   └── Implement per implementation.md (Pane pattern + adaptive density)
│
├─► New component?
│   ├── What Z-layer? (ground / surface / floating / overlay) → spatial.md
│   ├── What material? → materials.md
│   ├── Interactive? (hit targets ≥ 44px, keyboard reachable) → interaction.md
│   └── Run review-checklist.md § Lens 2 (Spatial Readiness)
│
├─► Multi-user or governing surface?
│   ├── Map archetypes involved → ecosystem.md
│   ├── Add cascade indicators for governing actions
│   ├── Surface autonomic actor state (resolver, indexer, queue)
│   └── Run review-checklist.md § Lens 3 (Ecosystem Awareness)
│
├─► Visual polish pass?
│   ├── Replace solid backgrounds with materials → materials.md
│   ├── Add depth via Z-layer model → spatial.md
│   ├── Add progressive disclosure to dense surfaces → interaction.md
│   └── Verify inclusive design checks → § Appendix (below)
│
├─► Animation / spatial motion?
│   ├── View transitions for navigation morph → ./implementation.md § View Transitions
│   ├── Scroll-linked depth → spatial.md
│   └── Respect prefers-reduced-motion (MANDATORY)
│
├─► Generative UI / AI surface?
│   └── UIAtom composition pattern → generative-ui.md
│
└─► Need inspiration or direction?
    └── § Appendix — Inspiration & Frameworks (below)

---

Progressive Immersion Strategy

Build one semantic core that scales across capability tiers. Do not build separate apps.

Tier 1: Text / Voice (lowest bandwidth, highest accessibility)
├── Logic exposed as API for voice agents and chatbots
├── Serves lowest-bandwidth users, screen readers, CLI
└── Green Goods: offline-first service worker serves this tier

Tier 2: 2D Screen (mobile + desktop)
├── Same logic wrapped in standard UI components
├── Responsive via container queries (not just media queries)
└── Green Goods: current PWA client and admin

Tier 3: Spatial (headsets, AR, large displays)
├── 2D components "explode" into 3D floating panes
├── Depth, gaze, gesture become available
└── Green Goods: future — prepared via glass pane patterns, concentricity, view transitions

The bridge: Each tier is additive. Tier 2 includes everything from Tier 1. Tier 3 includes everything from Tier 2. Nothing is spatial-only — that's a core rule from Inclusive Design (see Quad Foundation above).

This maps to Green Goods' offline-first architecture: the offline state (service worker, IndexedDB) IS Tier 1. The PWA is Tier 2. The codebase is spatially-prepared via glass panes (spatial.md), container queries (interaction.md), and view transitions (implementation.md § View Transitions).

---

Related Surfaces

• implementation.md — Implementation tooling: dialogs, component runbook, Storybook, i18n, view transitions
• .claude/context/shared.md — Hooks, stores, error utilities behind the components
• .claude/context/client.md — Offline-first patterns, sync state as ambient UI indicators
• review — boundary/coherence judgment when surface decomposition is in question

---

Appendix — Inspiration & Frameworks

Folded into this file from the former references.md during the 2026-04-17 skill consolidation. This is reading-list depth — use when you need direction, not when you need tokens (see quick-reference.md for that).

Books

Book	Author	Key Concept
Laws of UX	Jon Yablonski	Psychology-backed design heuristics (Fitts's Law, Hick's Law, Miller's Law)
Refactoring UI	Adam Wathan, Steve Schoger	Visual design for developers — spacing, hierarchy, color, typography
The Design of Everyday Things	Don Norman	Affordances, signifiers, mapping — timeless interaction principles
Designing Interfaces (3rd ed.)	Jenifer Tidwell et al.	Pattern library for interaction design
Designing for Spatial Computing	O'Reilly (2025)	visionOS principles, gaze+pinch, window management

Designers & Studios

Who	Known For	Follow For
Rauno Freiberg (Vercel)	Spatial web effects, liquid interfaces	Bleeding-edge CSS/motion
Paco Coursey (Linear)	Precision minimalism, keyboard-first	Command surface craft
Lee Robinson (Vercel)	Developer-facing design systems	Performance-aware design
Stripe Design	Glass materials, data-dense elegance	Financial/data UI
Linear	GPU-rendered UI, keyboard navigation	Operator tools, control panes
Apple HIG (Spatial)	visionOS guidelines	Material system, gaze patterns
Diagram (Rive)	Interactive motion design	Cross-platform micro-interactions

Inspiration Sources

Source	Use For
Godly	High-end visual direction, animation
Refero	Real-world UI patterns by interaction type
Mobbin	Mobile/web app flow analysis
UXArchive	User flow recordings
Awwwards	Boundary-pushing sites with tech breakdowns

Tools

Tool	Use For
Figma (AI features)	Layout generation, design-to-code
Rive	Interactive motion graphics, stateful animations
Spline	3D web experiences, spatial UI prototyping
Motion (Framer Motion)	Production React animations, layout gestures
View Transitions API	Native morphing navigation — see implementation.md § View Transitions

Research & Frameworks

Source	Authority On
Nielsen Norman Group	Research-backed usability, AI UX, spatial interaction
Growth.Design	Interactive case studies on product psychology
Baymard Institute	E-commerce UX benchmarks
Material Design 3	Adaptive tokens, dynamic color, motion
Material 3 Expressive (Google I/O 2025)	Spring-based motion tokens, shape morphing, expressive color, hero moments, wavy progress
Liquid Glass (Apple WWDC 2025)	Concentricity (3 shape types), functional glass layers, source-anchored interaction, scroll edge effects, symbol-first nav
Microsoft Inclusive Design	inclusive.microsoft.design — Persona Spectrum, cognitive inclusion
Rethinking Users (Youngblood, Chesluk, Haidary)	rethinkingusers.com — 15 user archetypes, ecosystem mapping
EPIC 2023 — Friction & Ease in Complex Systems	Ethnographic frictions, systems phenomena, user ecosystem theory

---

Note: This skill was previously named frontend-design. The broader scope (ecosystem thinking, inclusive design, bot/docs tone) warranted the simpler name.