Specs

Why Specs exist

The menu and the recipe card

A human handing a spec document to a friendly robot — representing Context Grammar as an instruction manual for AI

When a restaurant opens a new branch, the head chef writes a standardized recipe card. Not "slow-cooked chicken." The card reads: chicken thigh 180 g · oil temp 78°C ± 2 · cook time 90 min · salt ratio 1.2%.

The menu description lets guests imagine the dish. The recipe card lets any kitchen reproduce it exactly. Same dish, two different languages for two different readers.

Context Grammar works the same way. The narrative in a portfolio chapter lets a designer understand a scene. The Spec lets an iPhone, a fridge, and a car dashboard act on that scene correctly — without anyone re-explaining it three times.

Two faces of every Token

Human side and machine side

The same fact, written twice. One for understanding, one for execution.

📖

Narrative

Human face

Written for designers, reviewers, and stakeholders. Prose carries context, emotion, and story.

"7:02 AM — Mai is making lunch boxes while getting dressed for work"
Emotion and background included
Used in reviews and discussions
Portfolio chapters are this

vs

⚙️

Spec

Machine face

Written for AI and devices. JSON carries value, range, confidence, and source — zero ambiguity.

cognitive_load: 0.82
Value · range · confidence · source
Used in implementation
YAML / JSON files

Narrative is the language of conversation. Spec is the language of execution. The same fact, written for two different readers. When a portfolio chapter says "Mai is overwhelmed at 7 AM," there is always a corresponding Spec behind it.

Step by step

A Tuesday morning becomes a Spec

Here is how a scene from the portfolio narrative becomes a machine-readable JSON file.

"7:02 AM. Mai is making her son's lunch while getting ready for work. The children are shouting in the living room. Cognitive load is high."

— P1 Living Home · A Tuesday Morning

1 Write the narrative (for humans) Narrative

This is the sentence that appears in the portfolio. The reader is a designer, reviewer, or hiring manager. It carries context, emotion, and story — and a human immediately understands "Mai is under pressure right now." But this sentence alone does not tell an iPhone how to behave.

2 Find the Tokens inside the narrative Tokenize

The narrative has Context Tokens embedded in it. A designer extracts them:

Cognitive Load — "lunch boxes + getting dressed + shouting children" → high
Physical State — "cooking, hands occupied"
Social Exposure — "home, family only" → private
Form Factor — "kitchen iPhone"

The narrative implicitly contains four Tokens. The next step makes them explicit.

3 Write the Spec (for machines) Spec / JSON

The same scene, rewritten as machine-readable JSON. Same meaning — different format.

// yamashiro-mai-0702.json

{
  "context_id": "mai-tuesday-morning",
  "timestamp": "2026-04-30T07:02:00+09:00",
  "spec_version": "v1.2",

  "tokens": {
    "cognitive_load": {
      "value": 0.82,        // 0.0–1.0 scale
      "confidence": 0.74,
      "source": "calendar+activity+time-of-day"
    },
    "physical_state": {
      "value": "hands_busy",
      "confidence": 0.91,
      "source": "kitchen-presence + cooking-activity"
    },
    "social_exposure": {
      "value": "family_private",
      "confidence": 0.99,
      "source": "location=home + bluetooth=family-only"
    },
    "form_factor": {
      "value": "iphone-kitchen",
      "confidence": 1.00
    }
  },

  "projection_rules": {
    "voice_priority": true,
    "text_density": "low",
    "interaction_steps": "max_1"
  }
}

4 The AI and devices read the Spec Render

The iPhone voice agent reads this Spec and decides: cognitive_load = 0.82, hands_busy = true → skip text UI, complete in one voice step.

If Mai were in the car at the same moment, CarPlay would read the same Spec differently. But the Spec does not change. Each device translates it according to its own capabilities.

5 Narrative and Spec are confirmed to agree Result

Narrative: "Mai is overwhelmed, hands full."
Spec: cognitive_load=0.82, physical_state=hands_busy

Same fact, two formats. Neither is lying. That is why the portfolio story and the device behavior always match.

→ Narrative ≡ Spec (same meaning, different format)

Compile once, render anywhere

One Spec reaches six devices

Three phone screens side-by-side showing UI adapting across different contexts — the same Spec rendered differently per device

The designer writes cognitive_load: 0.82 and nothing else. Each device translates that single value into its own surface behavior. No device-specific rewrites needed.

How each device reads the same Spec (cognitive_load=0.82, hands_busy=true)

📱

iPhone (kitchen)

Voice, one step. Text UI hidden.

❄️

Samsung Family Hub

Large icon + one tap. Minimal text.

🚗

CarPlay

Voice only. Visual UI disabled.

🏠

Nest Hub

Voice + large visual confirmation.

⌚

Apple Watch

Haptic + voice. Screen not assumed.

💻

MacBook (study)

Full UI — not relevant in this context.

The Spec author never thought about iPhone, CarPlay, or a fridge. They wrote cognitive_load=0.82 and nothing more. Each device translated that on its own.

When a new device arrives — XR glasses, car HUD — the Spec does not change. The new device adds a translation rule. This is what "implementation-agnostic" means in practice.

Universal contract

The same Specs flow from every Brain

Three interlocking building blocks labeled Tokens, Brain, and Rules — the three spec files that form Context Grammar's portable contract

Specs are defined per Token — not per Brain. Whether the Spec originates from a Person Brain, a Domain Brain, or a Project Brain, the structure is identical. The Token fields do not change based on which Brain produced them.

This means a Team Brain and a Home Brain both emit the same cognitive_load field with the same five required keys. A device reading one type of Brain does not need a different parser for another.

Person Brain

Emits cognitive_load, social_exposure. Same fields, person-specific sources.

Domain Brain

Finance, health, travel — each Brain emits the same Token fields. Domain changes the values, not the schema.

Project Brain (P4)

Enterprise Brain instances produce the same Spec contract. One parser reads all Brain types.

Brain is the memory entity. Spec is the output format. These are separate concerns. Switching from a Home Brain to an Enterprise Brain changes the memory model — not the Spec schema.

Forward compatibility

v1 → v2 → v3 without breaking old surfaces

Context Grammar will keep evolving. New Tokens, new Dials, new AX Patterns will be added. A fridge UI built in 2026 should still work with a 2030 Spec. That requires versioning.

Spec version history

v1.0

Initial 7 Tokens. Cognitive Load · Physical State · Social Exposure · Priority Weight · Form Factor · Feasibility · Synchro Rate (predecessor to Autonomy). Released 2025-12.

v1.2

Synchro Rate renamed → Autonomy Dial. Behavior unchanged. Old field kept as alias — surfaces reading v1.0 continue working.

v2.0

Disclosure Dial added → 8 Tokens. Old surfaces that do not read Disclosure keep working — a default value is injected. Only new surfaces respond to the Disclosure field.

v2.3

Substitution Modes added to Spec. Exact · Flexible · Exploring · Surprise are selectable. A P1 v1 fridge UI stays on Exact and continues to work.

v3.0 (planned)

Multi-Person Orchestration as a first-class concept. One Spec represents the full family's state. Surfaces reading v2 extract a single person's slice and continue working.

Three forward-compatibility rules

01

Add new fields — always allowed

Old surfaces ignore unknown fields. No breakage.

02

Delete fields — never allowed

Old surfaces will break. Keep as alias instead.

03

Change a field's meaning — never allowed

Give the new concept a new name. Rename, don't redefine.

Spec anatomy

Five fields every Spec must include

An engineer plugging a Context Brain module into a server rack — representing the technical, machine-readable Spec contract

Any Spec with these five fields is machine-readable, reviewable, and evolvable. This is the minimum contract.

Field	What it declares	Example
token_id	Which Token this entry describes	cognitive_load
value	The Token's current value (number, enum, or range)	0.82 (0.0–1.0 scale)
confidence	How certain the estimate is	0.74 (74% confidence)
source	Where the value came from	calendar+activity+time-of-day
projection_rules	Hints passed to the UI layer	voice_priority: true

Confidence matters because Cognitive Load is estimated, not measured. At 70% confidence, the system treats a value as 70% reliable — triggering a check-in rather than silent action. This confidence value is the mechanical foundation of the Autonomy Dial: high confidence → Auto; low confidence → Suggest.

Common questions

Q&A

Q1. Who writes the Spec — designer or engineer?

The designer writes it first. A Spec is not an implementation detail — it is a declaration of meaning. "The cognitive load in this scene is 0.82" is a design decision. The engineer then implements how each device translates that value into behavior. The Spec is a design artifact.

Q2. Does it have to be JSON? Can I use YAML or TOML?

Any format works. JSON is easy for machines, YAML is easier for humans — that is the only difference. The Context Grammar Spec is valid in any format as long as the five fields are present. The existing design-rules.yaml is written in YAML. Structure matters, format does not.

Q3. What does the AI do when confidence is low?

It asks or waits. If cognitive_load.confidence = 0.45, the system asks a minimal confirmation: "Is now a good time?" (Autonomy Dial shifts toward Suggest). If confidence = 0.95, it acts without asking (Autonomy Dial at Auto). The confidence field sets the AI's hesitation level.

Q4. What if the narrative and the Spec disagree?

One of them is wrong — fix both. Narrative and Spec are two representations of the same fact. If they diverge, the design is incoherent. Check them together in review. Disagreement between the two is a design bug, not an editorial choice.

Q5. How is this different from OpenAPI or JSON Schema?

Different layer, different purpose. OpenAPI defines the shape of API requests and responses. JSON Schema validates that data types are correct. Context Grammar Spec declares the meaning of a UX scene. A Spec can be described with JSON Schema — but its goal is not type validation, it is answering "what does this scene mean for the user?"

Use it in your project

Everything you need to implement Context Grammar

The spec is open. The SDK is zero-dependency TypeScript. The JSON Schema validates your ContextState at build time. All formats are designed to drop into any codebase.

Pure function. Zero dependencies. Runs in any JS runtime. Input: 8 enums. Output: fired patterns, design rules, autonomy validity.

npm install @context-grammar/core

README →

Use in your IDE, CI pipeline, or at runtime to validate that a ContextState object is well-formed before passing it to the engine.

context-grammar.schema.json ↓

All 8 token enums, ContextState, EvaluationResult, AXPattern, and design rule types. Works standalone — no SDK install required.

context-grammar.d.ts ↓

All 8 Context Tokens — enum values, trigger conditions, estimation methods, and the Disclosure × Autonomy gate. Human-readable and machine-parseable.

context-tokens-spec.yaml ↓

All 23 AX Patterns — trigger predicates, design rules, success criteria, cross-pattern composition rules, and substitution modes.

ax-patterns-spec.yaml ↓

Step-by-step guide for integrating Context Grammar into a product: token estimation, Brain schema, rule engine wiring, and forward-compatibility rules.

IMPLEMENTATION.md →

The Spec is the handshake between design and execution.

Tokens define what to read. Brain provides the memory. Specs carry the meaning forward — to every device, every version.

8 Context Tokens Context Brain Rule Engine

← Back to Context Grammar

The spec, running in your browser.

The menu and the recipe card

Human side and machine side

A Tuesday morning becomes a Spec

One Spec reaches six devices

The same Specs flow from every Brain

v1 → v2 → v3 without breaking old surfaces

Five fields every Spec must include

Q&A

Everything you need to implement Context Grammar

The Spec is the handshake between design and execution.