Product Design Capsule | Gakaso for AI Agents | Docspi | docspi
Product Design Capsule
Published July 22, 2026
# Product Design Capsule (`gakaso_set_design_capsule` / `gakaso_get_design_capsule`)
The Product Design Capsule is a per-project, structured design brief that Gakaso's own generation paths (the "Gakaso AI" mode described in `/ai/generation.md`) consult when generating on a project's behalf. As an external agent, you can also read and write it directly — it's a useful place to record and retrieve a project's design intent so it doesn't have to be re-derived (or re-explained by the human) every session, and to keep your own generation choices consistent with whatever direction has already been set.
This is a **generic, fully project-agnostic data structure** — it is not the same thing as Gakaso's internal design-quality rubric (see `/ai/generation.md` and `/design/diagram-intelligence.md` for that distinction) or the `gakaso://manuals/design-principles` resource; the Capsule is *this project's own* brief, which you fill in, not a body of universal design guidance.
## Storage and authorization
- `gakaso_set_design_capsule` upserts the capsule as JSON; `gakaso_get_design_capsule` retrieves it (returns `{ found: false, capsule: null }` if none has been set yet — not an error).
- `set` requires `write` permission on the project; `get` requires `read` (same RBAC layer as everything else — see `/mcp/overview.md`).
- There is exactly one capsule per project (no versioning/history beyond an `updatedAt` timestamp) — calling `set` again replaces the whole thing, not a partial merge, so if you're changing one field, fetch the current capsule with `get` first and send back the full object with your change applied.
## Shape of the capsule
`gakaso_set_design_capsule` takes `{ projectId, capsule }` where `capsule` is an object with these top-level sections (all required except `openQuestions`):
| Section | Fields | Purpose |
|---|---|---|
| `metadata` | `productId`, `productName`, `capsuleVersion`, `capsuleOwner`, `lastSynced`, `repositoryPath?`, `relatedGakasoProject?` | Identifies the product/capsule itself. Leave `repositoryPath` unset if you're committing the capsule anywhere — it's meant to stay local. |
| `purpose` | `coreProblem`, `primaryUsers[]`, `usageFrequency` (`daily`/`weekly`/`occasional`), `tensionLevel` (`high`/`medium`/`low`), `successState` | What the product is *for*, in one-sentence terms, and how emotionally high-stakes it is for users. |
| `designDirection` | `targetImpression[]`, `avoidImpression[]` (both ≤5 adjectives), `screenDensity` (`high`/`medium`/`low`), `domainPatterns[]`, `targetPlatforms[]` | The intended feel, and what to actively avoid — this is the section most directly useful for steering your own generation tone. |
| `aesthetic` | `layout`, `typography`, `color`, `surface`, `iconImagery`, `motion` (free-text per facet) | A short prose description of the aesthetic per visual facet. |
| `tokenStrategy` | `colorTokens[]`, `typographyTokens[]`, `spacingTokens[]`, `radiusElevationTokens[]`, `productExceptions[]` | Which design tokens (see `/design/tokens.md`) matter most for this product, plus any explicitly allowed exceptions to the token system. |
| `ia` | `primaryScreens[]`, `primaryStates[]`, `navigationPolicy`, `listDetailPolicy` | Information-architecture conventions — what screens/states exist and how navigation/list-vs-detail should generally behave. |
| `componentStrategy` | `coreComponents[]`, `requiredVariants[]`, `prohibitedPatterns[]` | Which components are core to this product, which variants must exist, and patterns to avoid when generating. |
| `a11y` | `wcagTarget` (`AA`/`AAA`), `keyboardRequirements[]`, `accessibilityTreeChecks[]`, `computedStyleChecks[]`, `responsiveBreakpoints[]` | Accessibility bar and checks this project holds itself to. |
| `openQuestions` (optional) | array of strings | Anything left undecided — a place to record ambiguity rather than silently picking an answer. |
None of these fields are Gakaso-proprietary content — they're a brief *you* (or a human) write about *this specific product*. If a project doesn't have a capsule yet and a human asks you to "set up the design brief," this schema is what you're filling in; ask for (or infer from prior conversation/existing canvas content) enough to populate `purpose` and `designDirection` at minimum — the rest can start sparse and be filled in over time.
## Typical call sequence
1. At the start of a generation-heavy session, call `gakaso_get_design_capsule` — if `found: true`, read `designDirection`, `aesthetic`, `tokenStrategy`, and `componentStrategy` before creating any canvas content, so your output matches the project's established direction rather than drifting from it.
2. If `found: false` and the task involves generating a non-trivial amount of new UI, consider proposing a capsule to the human (at least `purpose` + `designDirection`) rather than generating blind — or proceed without one if the task is small/one-off.
3. After calling `gakaso_set_design_capsule`, the response confirms `{ projectId, saved: true, productId, capsuleVersion, updatedAt }` — there's no separate "validate" step; a malformed capsule (missing a required section) is rejected by schema validation at call time rather than stored partially.
4. If you're updating one field (e.g. adding a `prohibitedPatterns` entry after a human corrects your output), `get` first, mutate the returned `capsule` object client-side, then `set` the whole thing back — there is no field-level patch tool.