Design Memory

Design Memory — the .sumi/ contract

.sumi/ is what makes the commands compose. /style decides a visual direction once; /screen, /component, /page, /fix and a dozen others consume it instead of re-inventing a palette every invocation.

That only works if every command agrees on the file shape. Until v4.1.0 none was written down, and four commands wrote .sumi/style.json in four different shapes while other commands read whichever they assumed. This skill is the single definition.

Constants

The canonical .sumi/style.json. Every writer emits this envelope; nobody invents keys.

{
  "$sumi": "1",
  "meta": {
    "generated": "ISO-8601 timestamp",
    "updatedBy": ["/style"],
    "sector": "fintech",
    "mood": "professional",
    "platform": "web"
  },
  "project": {
    "framework": "react | vue | svelte | vanilla | swiftui",
    "styling": "tailwind | css | styled-components | swiftui",
    "typescript": true
  },
  "tokens": {
    "$schema": "https://design-tokens.github.io/community-group/format/",
    "color": {},
    "typography": {},
    "space": {},
    "radius": {},
    "shadow": {},
    "duration": {},
    "easing": {},
    "z": {},
    "$themes": { "light": {}, "dark": {} }
  },
  "tone": {
    "formality": "",
    "traits": [],
    "wordsToUse": [],
    "wordsToAvoid": []
  },
  "references": [
    { "app": "", "platform": "", "stealThis": "", "takeaway": "" }
  ]
}

Everything under tokens is W3C DTCG. Everything outside it is Sumi's own envelope, because DTCG has no way to express a sector, a tone of voice, or a list of reference apps.

The file set

| File | Written by | Holds | |---|---|---| | .sumi/style.json | /style, /palette, /type, /tokens, /dark | the schema above | | .sumi/brief.json | /brief | persona, HMW questions, constraints, success criteria | | .sumi/map.json | /map | sitemap, screen inventory, content hierarchy | | .sumi/vision.json | /grade | visual direction, designer-DNA match, score | | .sumi/wireframe-.json | /wireframe | layout structure, component map | | .sumi/generated-.json | /generate | generation records, prompts, model, score | | .sumi/decisions.log | any command | append-only NDJSON: {ts, command, decision, reason, overrides} |

Ownership

A writer touches its own subtree and nothing else. This is what allows four commands to share one file without clobbering each other.

| Command | Owns | |---|---| | /style | the whole file — it is the only command that may create it | | /palette | tokens.color | | /type | tokens.typography | | /tokens | tokens.* (serialization only; it does not decide) | | /dark | tokens.$themes.dark | | everything else | read-only |

Read order

Broad to specific. Later files override earlier ones where they overlap.

1. brief.json — who it is for and what problem it solves
2. map.json — what screens exist
3. style.json — what it looks like
4. vision.json — the visual bar and DNA match
5. wireframe-.json — the layout of the screen actually in play
6. decisions.log — the running override log; the last entry wins

Merge rules

1. Read-modify-write, never replace. Load the file, deep-merge your subtree,

write it back. Append your command name to meta.updatedBy and refresh meta.generated. A whole-file replacement destroys three other commands' work and is the specific bug this contract exists to prevent.

1. Precedence: explicit user instruction > design memory > defaults. An

instruction in the current turn wins immediately and appends to decisions.log with its reason.

1. Absent is not empty. No file means "not decided yet" — generate a value

and offer to persist it. A file present but partial means "decided" for the sections that exist; fill only the gaps.

1. Never invent a token when style.json exists. If the palette is on disk,

use it. Inventing a second palette mid-session is the most visible way to break the illusion that the commands are one system.

1. Conflict: ask once. If your write would change a value another command set

in a previous session, surface both values in one line and ask. Do not ask twice in a session, and do not silently overwrite.

Routing

For the full JSON Schema of every file, worked merge examples, and the migration note for pre-v4.1.0 files: read references/sumi-file-schemas.md.

Cross-References

• design-systems-architecture — the DTCG token tiers tokens serializes
• design-token-presets — vetted starting token sets to seed tokens from
• sumi-orchestrator — pipelines that span several commands, which is when

design memory earns its keep

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: phazurlabs
• Source: phazurlabs/sumi
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.