GRIDGEIST
Menu
ไทยGitHub ↗

Field manual / v1.2

FROM SIGNAL
TO SYSTEM.

A decision-first guide to creating, redesigning, or reviewing an interface that belongs to its product—not to a house style.

VERSION
1.2.0
ENTRY MODES
03
LICENSE
MIT

01 / Quickstart

Give the agent
a decision surface.

Invoke $gridgeist, name the product and audience, choose the job, preserve what matters, and define the evidence required before completion.

  1. 01Open the real surface

    Repository, rendered page, routes, content, and established brand.

  2. 02Name the decision

    Create, redesign, or review—and the outcome that should become true.

  3. 03Bind the proof

    Viewports, interactions, keyboard paths, project checks, and known limits.

PROMPT / CREATE
Use $gridgeist to design a landing page for a SQL learning platform.
Make the lesson, query editor, and results the visual evidence.
Avoid generic SaaS card grids.
Verify desktop, mobile, keyboard use, and accessibility.

Good context compounds. Let the agent inspect the repository and the rendered interface whenever possible.

02 / Install + update

Choose the path
you can maintain.

01

Codex plugin

RECOMMENDED

Add the marketplace, install the plugin, then start a new Codex session.

codex plugin marketplace add ohmiler/gridgeist
codex plugin add gridgeist@gridgeist
02

Compatible agents

UNIVERSAL

Use the open Agent Skills CLI for Claude Code, Cursor, Gemini CLI, Copilot, OpenCode, and other compatible agents.

npx skills add ohmiler/gridgeist -g
03

Manual

PORTABLE

Copy skills/gridgeist/ into the skills directory used by an agent that supports the Agent Skills SKILL.md convention.

04

Update an existing install

EXPLICIT

Gridgeist does not update silently. Refresh and reinstall a Codex plugin, or use the Skills CLI update command, then start a new agent session. Manual copies must be replaced from a tagged release.

codex plugin marketplace upgrade gridgeist
codex plugin add gridgeist@gridgeist

npx skills update gridgeist -g -y

03 / Choose a mode

One method.
Three entry points.

MODEUSE WHENSTART WITH
CreateBuilding a new interfaceAudience + primary task + authentic evidence
RedesignChanging a working productPreserved behavior + brand signals + state inventory
ReviewDiagnosing a draft before editsPrioritized findings + evidence

04 / Adapt the system

Expose only the structure
the product needs.

Choose visibility from audience, task, content, and brand. Gridgeist is the decision method—not the visible treatment.

VISIBLEData + technical

Let relationships, commands, status, and operational evidence align on explicit tracks.

QUIETContent + editorial

Use controlled measure and persistent orientation while prose or imagery leads.

INVISIBLECanvas + direct action

Let the primary tool dominate; keep structure in control placement and behavior.

STATE-LEDTransactional flow

Use stable controls, explicit validation, confirmation, and recovery to form hierarchy.

RECOGNIZABILITY TESTIf the borders, mono labels, and visible grid disappear, the result should still belong to the product.

05 / Define the contract

Connect the system
before polishing it.

Use the smallest complete contract for the work. Reconcile existing implementation and brand evidence before changing values.

01 / FoundationPalette · type · rhythm
02 / SemanticCanvas · text · state
03 / ComponentAnatomy · variant · behavior
Color + themesPair roles.

Map foreground/background, border, action, focus, success, warning, and destructive relationships.

Type + spacingName jobs.

Define only the display, heading, body, label, metadata, and spacing roles the surface needs.

ComponentsStress the grammar.

Cover variants, states, localization, dynamic content, overflow, and narrow containers.

Motion + evidenceBind the claim.

Use motion for feedback or causality, provide reduced motion, and report only what was observed.

FocusErrorReduced

06 / Write the brief

Four inputs remove
most ambiguity.

  1. 01

    Product + audience

    What is being designed, and who needs to use it?

  2. 02

    Mode + outcome

    Create, redesign, or review—and what should be true when the work is done?

  3. 03

    Constraints

    Name the behavior, routes, content, brand assets, and technology that must remain.

  4. 04

    Verification

    Specify viewports, interactions, keyboard paths, accessibility, and project checks.

Prompt pattern / Redesign +
Use $gridgeist to redesign this dashboard.
Preserve every route, function, content item, and brand color.
Rebuild the hierarchy around the user's primary investigation path.
Verify narrow mobile, tablet, laptop, and wide desktop widths.
Prompt pattern / Review +
Review this interface with $gridgeist without editing it yet.
Give me a one-line verdict, prioritized findings with evidence,
and one coherent replacement direction.

07 / Workflow

Inspect before composing.

  1. 01Inspect

    Understand the product, audience, routes, components, tokens, and rendered UI. If several thesis-level directions remain credible, recommend two or three and confirm one before editing.

  2. 02Set a thesis

    Write one sentence that governs hierarchy, structure, expression, and product evidence.

  3. 03Define the system

    Connect foundation values to semantic roles and shared component anatomy, variants, states, content stress, motion, and responsive transformations.

  4. 04Compose

    Build hierarchy before detail. Let real code, data, workflows, or imagery carry visual weight.

  5. 05Implement

    Follow repository conventions, semantic HTML, keyboard behavior, and existing primitives.

  6. 06Verify

    Render representative widths, exercise states and inputs, fix observed issues, and report remaining gaps.

08 / Verification

Evidence before
the verdict.

A

Clarity

Product, audience, primary task, and next action are obvious.

B

Hierarchy

Each viewport has one dominant element and a readable order.

C

Response

Mobile is recomposed around priority; code and tables do not overflow.

D

States

Default, loading, empty, error, success, disabled, and destructive states are considered when applicable.

E

Access

Landmarks, focus, names, contrast, motion, and keyboard paths are observed.

F

Integrity

Claims name the commands, viewports, flows, limits, and evidence actually observed.

6 / 6

FRESH v1.2 SYSTEM-CONTRACT RUNSScenario 19 implementations passed in English and Thai with independent responsive browser checks. Guardrails were repaired; real-user evidence remains open.

09 / Limits

A method,
not a preset.

  • Grid, type, and color defaults are starting points—not fixed rules.
  • Output quality depends on the product context available to the agent.
  • Automated checks do not replace inspecting the rendered interface.
  • Model output can vary; re-test when the agent or skill changes.

READY TO SEE THE METHOD IN PRACTICE?

Explore the field studies