Gridgeist

English · ภาษาไทย · Website · Examples

Gridgeist is an agent skill for creating, redesigning, and reviewing product-native web interfaces. It adapts structure, typography, imagery, interaction, and product evidence to the established brand, using grids as visible, quiet, or invisible logic. It helps agents move beyond generic AI-generated SaaS patterns while preserving product intent, behavior, responsiveness, and accessibility.

See the difference

This illustrative Northline logistics comparison is rendered from two full HTML/CSS pages with the same product, copy, sample operating data, and viewport. The After page and screenshot were rebuilt with the Gridgeist v1.2.0 system workflow; Northline and all displayed data are fictional.

Same content and sample operating data; a different design system. Gridgeist turns the topology, route table, exception, actions, and metrics into one connected operational surface built from product evidence, while labeling the concept honestly. Both README images are browser captures of the working pages. Open the Before page or open the v1.2.0 After page.

What v1.2.0 changes

Gridgeist now treats visual decisions as one system, not a sequence of isolated styling choices.

Area v1.2.0 behavior
System contract Defines color, typography, layout, spacing, shape, components, states, media, and motion as one compact direction before implementation.
Semantic roles Connects foundation tokens to semantic roles and component decisions, so contrast and state relationships remain intentional.
Component grammar Gives related controls and content shared anatomy, variants, density, states, and content-stress rules instead of styling each instance separately.
Direction safety When the visual thesis is still broad, offers distinct directions and waits for alignment before committing tokens or editing the interface.
Skill coordination Names one direction owner when multiple UI skills are active, preventing competing visual systems.
Verification Checks representative widths, overflow, focus, interaction states, themes, and reduced motion—and limits claims to observed evidence.

In practice, the result is more coherent, less generic, and easier to extend without losing the product's identity. The v1.2.0 release was exercised through three English and three Thai system-contract scenarios, independent responsive browser checks, and repaired guardrail tests.

60-second Quickstart

  1. Install Gridgeist through the primary channel for your agent.

    For Codex, add the Git marketplace and install the plugin:

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

    For Claude Code, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and other compatible agents, use the universal installer:

    npx skills add ohmiler/gridgeist -g

    Manual fallback: If neither installer is available, continue to Manual installation.

  2. Start a new agent session in your web project and paste:

    Use the Gridgeist skill to review this interface without editing it yet. Give me a one-line verdict, prioritized findings with evidence, and one coherent redesign direction. Preserve the product's behavior and brand.

Agents that support explicit skill invocation can use $gridgeist in the prompt. Continue to Installation for product-specific details and more examples.

Use cases

  • Create a distinctive landing page, dashboard, documentation site, portfolio, or learning platform.
  • Redesign an existing interface without breaking its behavior or brand.
  • Review a draft and prioritize hierarchy, composition, responsiveness, accessibility, and implementation quality.
  • Adapt technical, editorial, image-led, playful, utilitarian, or visible-grid direction without erasing the brand.

Installation

Codex plugin

This repository is packaged as a Codex plugin through .codex-plugin/plugin.json. The plugin points to the same skills/gridgeist/ directory used by the other channels, so all installations share one source of truth.

Add the Gridgeist marketplace, then install the plugin:

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

Start a new Codex session after installation so the bundled skill is discovered.

Universal installer

For Claude Code, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and other compatible agents, install Gridgeist with the open agent skills CLI:

npx skills add ohmiler/gridgeist -g

The installer discovers skills/gridgeist/ and prompts you to choose the target agents. To select one directly, pass its agent name; for example:

npx skills add ohmiler/gridgeist -g -a claude-code

Manual installation

Use manual copying only when the plugin and universal installer are unavailable:

git clone https://github.com/ohmiler/gridgeist.git
Copy-Item -Recurse .\gridgeist\skills\gridgeist "$HOME\.agents\skills\gridgeist"

For a different agent, copy skills/gridgeist/ to that product's skills directory. The agent must support the Agent Skills SKILL.md convention. Discovery and invocation behavior can differ between products. Start a new agent session after copying the directory.

Updating

Gridgeist releases do not update silently. Use the command for the channel that installed the skill, then start a new agent session.

Codex plugin

Refresh the Git-backed marketplace snapshot, then reinstall the plugin version exposed by that release:

codex plugin marketplace upgrade gridgeist
codex plugin add gridgeist@gridgeist

Confirm the installed version with codex plugin list. If the current session still uses older instructions, start a new thread or restart the Codex app.

Universal installer

Update a global Gridgeist installation:

npx skills update gridgeist -g -y

For a project-scoped installation, use npx skills update gridgeist -p -y instead.

Git clone or manual copy

Run git pull --ff-only in an existing clone, then reinstall from skills/gridgeist/. Manual copies do not retain source or version metadata, so replace the complete skill directory from a tagged release. Prefer the Codex plugin or universal installer when future updates matter.

Example prompts

Invoke Gridgeist directly with $gridgeist and include four essentials:

  1. The product and its audience.
  2. The mode: create, redesign, or review.
  3. What must be preserved, such as behavior, brand color, or content.
  4. What must be verified, such as desktop, mobile, keyboard, and accessibility.
Use $gridgeist to redesign this Next.js course landing page. Preserve all behavior and the blue brand color, but replace the generic SaaS cards with an editorial grid and verify desktop and mobile layouts.

Review this dashboard with $gridgeist. Give me a one-line verdict, prioritized findings with evidence, and a coherent replacement direction before editing.

Use $gridgeist to create a technical documentation homepage where real API examples and navigation structure carry the visual identity.

Brief for a closer match

For a more precise result, provide these details when they are relevant:

  • Product and audience — what the product does and who uses it.
  • Primary task — the most important thing the user must accomplish.
  • Direction — the intended character, such as warm editorial, precise technical, or playful tactile.
  • Authentic material — product UI, data, prose, imagery, artwork, code, or a workflow that should carry visual weight.
  • Preserved constraints — brand signals, content, routes, behavior, components, privacy, or platform requirements that must not change.
  • Exclusions — visual language or behavior that would be wrong for the product.
  • Flows and states — the important default, loading, empty, error, success, disabled, and destructive paths.
  • Verification — representative viewports, keyboard, touch, focus, overflow, reduced motion, and primary flows to exercise.

When the direction is already clear, state it and let Gridgeist proceed without another aesthetic questionnaire. When several materially different directions are still credible, ask Gridgeist to inspect first, offer two or three grounded options with trade-offs and a recommendation, and wait for alignment before editing.

Copy and adapt this template:

Use $gridgeist to [create / redesign / review] [page or product surface].

Product and audience:
[What it does and who uses it]

Primary task:
[The most important user outcome]

Direction:
[A confirmed direction, or: Inspect first, propose two or three grounded
directions with trade-offs and a recommendation, and do not edit until I choose.]

Authentic material that should lead:
[Product UI / data / prose / imagery / artwork / code / workflow]

Preserve:
[Brand, content, routes, behavior, components, and constraints]

Avoid:
[Visual language or behavior that would be wrong]

Important flows and states:
[Primary flow and applicable default/loading/empty/error/success/disabled states]

Verify:
[Viewports, keyboard, touch, focus, overflow, reduced motion, and primary flow]

Inspect the repository and rendered interface before taking action.

Describe outcomes and genuine constraints rather than prescribing a CSS recipe. Unless they are established brand requirements, leave font sizes, spacing, radii, shadows, and column counts for Gridgeist to derive as one coherent system.

If a project already contains a DESIGN.md, theme, token set, or component library, Gridgeist inspects it alongside the implementation and rendered interface instead of assuming the sources agree. DESIGN.md is optional interoperability, not a dependency: Gridgeist should not create or update one unless you request a portable design-system artifact or explicitly include durable system documentation in the work.

Gridgeist also allows implicit invocation when the agent recognizes a matching web-interface task.

Working with companion skills

Gridgeist works best as the sole owner of product and visual direction, with optional companion skills supplying context, technical review, or rendered evidence. The lightest recommended workflow for most projects is:

Gridgeist -> Playwright

Gridgeist defines the interface thesis, hierarchy, system, and implementation direction. Playwright then checks the rendered result across representative viewports and interactions; it can also provide repeatable visual comparisons.

Situation Recommended workflow Division of responsibility
Most web projects Gridgeist -> Playwright Design and implementation, then rendered verification
Figma is the source of truth Figma -> Gridgeist -> Playwright Extract components, variables, and layout context; adapt them to the product and codebase; verify the result. See the Figma MCP server.
React or Next.js Gridgeist -> Vercel React Best Practices -> Playwright Own the interface direction; review framework performance; verify behavior. See Vercel Agent Skills.
Pre-release quality audit Gridgeist -> Web Quality Audit -> Playwright Review hierarchy and brand fit; audit accessibility, performance, SEO, and web quality; confirm the live result. See Web Quality Skills.
Original imagery is required Gridgeist -> image generation -> Gridgeist -> Playwright Establish the thesis before generating assets, compose with the selected assets, then verify the interface.

Treat these as optional workflows, not dependencies. Add only the companion that answers a real need, and keep another broad frontend-design or art-direction skill out of the same design phase; competing visual priors can weaken a coherent result. Companion skill names and availability vary between agents.

Example:

Use $gridgeist to redesign this interface while preserving its behavior and brand.
After implementation, use Playwright to verify representative desktop and mobile
viewports, keyboard interaction, overflow, and the primary user flow.

Repository layout

.codex-plugin/
  plugin.json          Codex plugin manifest
skills/gridgeist/      Installable skill
  SKILL.md             Trigger conditions and core workflow
  agents/openai.yaml   Agent-facing interface metadata
  references/          Design language and review checklist
evals/prompts.md       Repeatable manual behavior checks
docs/                  Design and implementation records

Case studies

Tracefield applies Gridgeist to a working developer-observability dashboard. Its repository preserves the generic baseline, exact prompt, evaluation rubric, tested trace domain, and responsive final interface.

Ledgerline tests the same skill on dense payment API documentation. Its repository preserves a conventional baseline, exact prompt, six-part rubric, deterministic API content, four viewport checks, and the responsive final interface.

Morrow stress-tests brand adaptation with a fictional image-led creative portfolio. Its repository preserves shared AI-generated artwork, a conventional baseline, exact prompts, a six-part rubric, four viewport checks, and a final interface deliberately unlike the technical case studies.

Doodlewood tests playful interaction design with a fictional, privacy-preserving children's drawing studio. Its repository preserves the generic baseline, exact prompt, six-part rubric, local drawing engine, four viewport checks, and explicit limits around child safety and real-user evidence.

Together, the four self-produced case studies cover data-heavy, content-heavy, image-led, and playful interactive surfaces. Further validation should now prioritize independent users, agents, and projects rather than adding another first-party visual category.

Limitations

  • Output quality depends on the agent inspecting the actual repository and rendered interface.
  • Automated checks do not replace visual inspection at representative viewport sizes.
  • The suggested defaults are starting points, not a mandatory preset for every brand.
  • Model outputs are not deterministic. Re-run evaluations when the skill or target agent changes.

Validation

Validate the installable skill structure:

python -X utf8 "$HOME\.codex\skills\.system\skill-creator\scripts\quick_validate.py" .\skills\gridgeist

Check release metadata and bilingual documentation without external dependencies:

python -X utf8 .\scripts\validate_release.py

Exercise clean installation and updates through the live Codex marketplace and universal installer. This check requires Codex, Node.js, npm, Git, and network access; it uses temporary homes and does not modify your existing installations.

python -X utf8 .\scripts\smoke_test_install.py

Behavioral evaluation prompts are in evals/prompts.md.

Contributing

Keep SKILL.md concise and place detailed, conditionally loaded guidance in references/. For behavior changes, update an evaluation scenario and record what failed before changing the skill. Open an issue or pull request with the motivating prompt and observed output.

License

MIT