Skip to content

Commit dabcb89

Browse files
Oba-OneOba-One
committed
feat(claude): add agent knowledge sandbox plan + design skill
Agent Knowledge Sandbox: comprehensive feature plan for sandboxed agent knowledge access with graph-based memory. Includes exploration research (1600+ lines), spec, context, lane files, QA checklists, and status.json. Design Skill: 9-file multi-lens design philosophy adapted from Green Goods. Four lenses (Regenerative, Spatial, Ecosystem, Compliance), Vellum material language, extension-specific constraints, implementation bridge to existing CSS tokens and component classes. Co-Roosted-By: Claude (Coop AI) <noreply@anthropic.com>
1 parent 359acac commit dabcb89

17 files changed

Lines changed: 3659 additions & 0 deletions

‎.claude/skills/design/SKILL.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
---
2+
name: design
3+
description: "Design philosophy for Coop's adaptive, warm, browser-first interfaces. Four-lens framework: Regenerative, Spatial, Ecosystem, Compliance. Vellum material language. Progressive disclosure. Use for design direction, visual decisions, component planning, and design review."
4+
version: "1.0.0"
5+
status: active
6+
packages: ["shared", "extension", "app"]
7+
dependencies: ["ui-compliance"]
8+
last_updated: "2026-04-05"
9+
last_verified: "2026-04-05"
10+
---
11+
12+
# Design Skill
13+
14+
Design philosophy and visual direction for Coop. This skill shapes *what* to build and *why* — the `ui-compliance` skill handles accessibility specifics, and `tokens.css` provides the implementation palette.
15+
16+
> **Paradigm**: The Adaptive Surface. Not pages — panes of contextual information that respond to intent, reveal on engagement, and recede when irrelevant. Warm, observant, and structured — never cold, surveillance-like, or overdesigned.
17+
18+
Adapted from Green Goods' design skill (same Quad Foundation), tailored for browser extension context, plain CSS tokens, and Coop's Vellum material language.
19+
20+
## Activation
21+
22+
| Domain | Keywords / Triggers | Sub-file |
23+
|--------|-------------------|----------|
24+
| **Design Philosophy** | design direction, paradigm, adaptive surface, vision | This file |
25+
| **Depth & Space** | Z-axis, depth, layers, elevation, scroll | [spatial.md](./spatial.md) |
26+
| **Interaction** | progressive disclosure, density, hover, touch | [interaction.md](./interaction.md) |
27+
| **Materials** | vellum, surface, warmth, opacity, grain | [materials.md](./materials.md) |
28+
| **Ecosystem** | members, operators, agents, cross-coop, cascade | [ecosystem.md](./ecosystem.md) |
29+
| **Regenerative** | regen, degen, capability, succession, growth-agnostic | [regenerative.md](./regenerative.md) |
30+
| **Implementation** | tokens, CSS, components, classes, build | [implementation.md](./implementation.md) |
31+
| **Review Checklist** | review, PR, audit, checklist, before merging UI | [review-checklist.md](./review-checklist.md) |
32+
| **References** | inspiration, design books, readiness checklist | [references.md](./references.md) |
33+
34+
When invoked:
35+
1. Establish design paradigm and material before writing code
36+
2. Apply Regenerative lens — does this regenerate or extract?
37+
3. Apply Ecosystem lens — whose experience composes with whose?
38+
4. Apply Inclusive Design lens — who gets excluded?
39+
5. Defer to `ui-compliance` skill for WCAG specifics
40+
6. Run the 4-lens review checklist on new components
41+
42+
---
43+
44+
## Quad Foundation
45+
46+
Four frameworks anchor every design decision, applied in order:
47+
48+
### 1. Regenerative Design
49+
50+
Does this design regenerate or extract? Seven principles: make the mycelium visible, design for succession, enrich the edges, failure is succession, growth-agnostic, capability is the deliverable, regen not degen.
51+
52+
Coop is a knowledge commons, not a content platform. The agent builds shared understanding, not engagement metrics. No streaks, no FOMO, no gamified entity counts. The Walkaway Test: if the agent stops, does the knowledge persist?
53+
54+
Full framework: [regenerative.md](./regenerative.md)
55+
56+
### 2. The Adaptive Surface Paradigm
57+
58+
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.
59+
60+
Not everything should be spatial. A settings form is a settings form. The paradigm applies when: the user monitors multiple streams (Roost), reviews candidates (Chickens), or explores decision history.
61+
62+
### 3. User Ecosystem Thinking
63+
64+
The interface exists in an ecosystem of interconnected people and agents. A single design decision cascades across members who may never see the same screen. Based on Youngblood, Chesluk, and Haidary's framework (BIS Publishers, 2021).
65+
66+
Coop adds a unique dimension: **agents are ecosystem actors**. The Coop agent is an Autonomic User whose behavior shapes every member's experience. It must have visible state — not hidden behind infrastructure.
67+
68+
Full framework with Coop ecosystem map: [ecosystem.md](./ecosystem.md)
69+
70+
### 4. Microsoft Inclusive Design
71+
72+
Three principles woven throughout:
73+
74+
- **Recognize Exclusion** — Extension UIs create specific exclusions: small popup viewport (400px), variable sidepanel width, color reliance in badges, dense information in compact cards.
75+
- **Learn from Diversity** — Progressive disclosure and adaptive density serve cognitive diversity, not just preference. Coop's founder has poor eyesight — design for that.
76+
- **Solve for One, Extend to Many** — Every pattern must work across popup (400px), sidepanel (variable), and PWA (full viewport). Constraints breed universal solutions.
77+
78+
---
79+
80+
## Paradigm Selection
81+
82+
Choose one paradigm per surface. Mix across a view.
83+
84+
| Paradigm | When | Feel | Density | Coop Example |
85+
|----------|------|------|---------|-------------|
86+
| **Command Surface** | Primary action area | Warm solid, sharp focus, high contrast | High — controls visible and ready | Nest Sources, Popup capture |
87+
| **Ambient Display** | Status, background info | Translucent, soft, peripheral | Low — glanceable, never demands attention | Source health dot, sync badge |
88+
| **Data Landscape** | History, traces, flows | Layered, navigable, zoomable | Variable — overview to detail | Decision History, Chickens review |
89+
| **Conversational** | Agent interaction, guidance | Minimal chrome, content-forward | Sparse — message and response | Agent approval prompts |
90+
| **Ritual** | Onboarding, success, ceremony | Full-screen, cinematic, focused | Single-purpose — one thing, done well | Coop creation, first source added |
91+
92+
### Material Metaphors
93+
94+
Coop uses **Vellum** as its primary material — warm, tactile, paper-like. This is dictated by the brand direction ("warm, not corporate") and the cream/brown palette.
95+
96+
| Material | Visual Language | When to Use |
97+
|----------|----------------|-------------|
98+
| **Vellum** (primary) | Warm cream, subtle grain, paper-like | All standard surfaces — cards, panels, forms |
99+
| **Vellum Dark** | Deep brown-ink, warm shadows | Dark mode variant — ink on dark paper |
100+
| **Warm Glass** | Cream-tinted translucency, soft blur | Ambient displays, source health, agent status |
101+
| **Earth** | Solid brown/green, grounded, dense | Command surfaces, operator controls |
102+
| **Glow** | Orange/green radiance, celebration | Ritual moments — coop creation, publish success |
103+
104+
The brand palette IS the material system:
105+
- `--coop-cream` = Vellum base
106+
- `--coop-brown` / `--coop-ink` = Vellum text
107+
- `--coop-green` = Knowledge/growth accent
108+
- `--coop-orange` = Action/publish accent
109+
- `--coop-mist` = Neutral/ambient backdrop
110+
111+
---
112+
113+
## Extension-Specific Constraints
114+
115+
Browser extensions impose unique design constraints that shape every decision:
116+
117+
| Context | Constraint | Design Response |
118+
|---------|-----------|----------------|
119+
| **Popup** | Fixed 400px width, max 600px height | Dense but scannable. Command Surface paradigm. No horizontal scroll. |
120+
| **Sidepanel** | Variable width (300-800px) | Container queries, not viewport breakpoints. Adaptive density. |
121+
| **Background** | No UI at all | N/A — but agent state must surface in popup/sidepanel |
122+
| **Offscreen** | Invisible document | Agent + graph engine = Autonomic actors. Make their state visible elsewhere. |
123+
124+
The popup is the **quick pulse**. The sidepanel is the **workspace**. Never put workspace-level complexity in the popup, never put pulse-level simplicity as the only sidepanel view.
125+
126+
---
127+
128+
## Anti-Patterns
129+
130+
### Design Philosophy
131+
1. **Dashboard-itis** — Cramming every metric onto one flat surface. Use progressive disclosure.
132+
2. **Cold corporate** — Grayscale dashboards, flat SaaS blue accents, sterile glassmorphism. Coop is warm and inhabited.
133+
3. **Surveillance-like** — Language or UI that makes passive observation feel aggressive. "I noticed" not "I tracked."
134+
4. **Overdesigned** — Fun lives in iconography, success states, and copy tone — not in making the review flow hard to scan.
135+
136+
### Coop-Specific
137+
5. **Generic AI slop** — Inter + purple gradient + white bg = forgettable. Coop has a distinctive warm palette. Use it.
138+
6. **Financial terminal** — Red/green PnL, countdown timers, FOMO urgency. This is a knowledge commons, not a trading floor.
139+
7. **Agent opacity** — Agent actions invisible until they produce output. Show the agent's state, knowledge, reasoning.
140+
8. **Source overload** — Showing all 214 entities at once. Progressive disclosure: topic bars → source cards → entity details.
141+
142+
### Visual Execution
143+
9. **Uniform density** — Same spacing everywhere. Adapt: comfortable for Roost, compact for Chickens, focused for Popup capture.
144+
10. **Color-only state** — Badges that rely on color alone. Always pair with text or icon (WCAG 1.4.1).
145+
11. **Motion without meaning** — Every animation communicates state change, not decoration. Respect `prefers-reduced-motion`.
146+
147+
---
148+
149+
## Decision Tree
150+
151+
```text
152+
What kind of design work?
153+
│
154+
├── New view or tab section?
155+
│ ├── Choose paradigm (Command / Ambient / Data / Conversational / Ritual)
156+
│ ├── Choose material (Vellum / Warm Glass / Earth / Glow)
157+
│ ├── Apply Regenerative lens (does this regenerate or extract?)
158+
│ ├── Apply Ecosystem lens (who is affected? what cascades?)
159+
│ ├── Define disclosure layers (glance → scan → engage → deep dive)
160+
│ └── Check: works in popup (400px)? works in sidepanel (variable)?
161+
│
162+
├── New component?
163+
│ ├── What Z-layer? (ground / surface / floating / overlay) → spatial.md
164+
│ ├── What material? → materials.md
165+
│ ├── Interactive? (hit targets ≥ 44px, keyboard reachable)
166+
│ ├── Reuse existing class? → Check global.css, CLAUDE.md component list
167+
│ └── Run review checklist → review-checklist.md
168+
│
169+
├── Agent-facing surface?
170+
│ ├── Agent is an Autonomic actor → ecosystem.md
171+
│ ├── Show agent state as Ambient Display (not hidden)
172+
│ ├── Reasoning traces use Data Landscape paradigm
173+
│ └── Source provenance uses progressive disclosure
174+
│
175+
├── Multi-user surface?
176+
│ ├── Map archetypes involved → ecosystem.md
177+
│ ├── Add cascade indicators for governing actions
178+
│ ├── Surface autonomic actor state (agent, sync, onchain)
179+
│ └── Run Ecosystem Readiness Checklist → ecosystem.md
180+
│
181+
├── Visual polish pass?
182+
│ ├── Replace solid backgrounds with Vellum material → materials.md
183+
│ ├── Add depth via Z-layer model → spatial.md
184+
│ ├── Add progressive disclosure to dense surfaces → interaction.md
185+
│ └── Verify inclusive design checks → review-checklist.md
186+
│
187+
└── Need inspiration?
188+
└── Reference library → references.md
189+
```
190+
191+
---
192+
193+
## Related Skills
194+
195+
- `ui-compliance` — WCAG 2.1 AA, forms, responsive, animation, dark mode
196+
- `react` — Component composition, state management, performance
197+
- `data-layer` — Dexie, Yjs, offline-first patterns, sync indicators
198+
- `architecture` — System boundaries that influence surface decomposition

0 commit comments

Comments
 (0)