Skip to content
Back to search

gridgeist

Gridgeist turns product intent into a rigorous visual system—without the generic AI SaaS aftertaste.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ohmiler--gridgeist/badge.svg)](/listings/ohmiler--gridgeist)

HTML

<a href="/listings/ohmiler--gridgeist"><img src="/api/listings/ohmiler--gridgeist/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](#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](#installation) for product-specific details and more examples.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 323 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="skills/gridgeist/assets/gridgeist.svg" alt="Gridgeist agent skill for web interface direction" width="240" />
  3. </p>
  4. # Gridgeist
  5. **English** · [ภาษาไทย](README.th.md) · [Website](https://ohmiler.github.io/gridgeist/) · [Examples](https://ohmiler.github.io/gridgeist/examples/)
  6. 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.
  7. ## See the difference
  8. 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.
  9. <table>
  10. <tr>
  11. <th width='50%'>Without Gridgeist - generic SaaS</th>
  12. <th width='50%'>With Gridgeist v1.2.0 - product-native system</th>
  13. </tr>
  14. <tr>
  15. <td><img src='docs/assets/northline-before.png' alt='Generic Northline logistics landing page with centered marketing copy, rounded controls, a chart, and interchangeable metric cards' width='100%' /></td>
  16. <td><img src='docs/assets/northline-after.png' alt='Gridgeist v1.2.0 Northline concept organized as one operational system with live freight topology, semantic lane states, arrival times, and an explicit priority exception' width='100%' /></td>
  17. </tr>
  18. </table>
  19. 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](https://ohmiler.github.io/gridgeist/readme-showcase/?view=before) or [open the v1.2.0 After page](https://ohmiler.github.io/gridgeist/readme-showcase/?view=after&rev=ab77ceb6).
  20. ## What v1.2.0 changes
  21. Gridgeist now treats visual decisions as one system, not a sequence of isolated styling choices.
  22. | Area | v1.2.0 behavior |
  23. | --- | --- |
  24. | System contract | Defines color, typography, layout, spacing, shape, components, states, media, and motion as one compact direction before implementation. |
  25. | Semantic roles | Connects foundation tokens to semantic roles and component decisions, so contrast and state relationships remain intentional. |
  26. | Component grammar | Gives related controls and content shared anatomy, variants, density, states, and content-stress rules instead of styling each instance separately. |
  27. | Direction safety | When the visual thesis is still broad, offers distinct directions and waits for alignment before committing tokens or editing the interface. |
  28. | Skill coordination | Names one direction owner when multiple UI skills are active, preventing competing visual systems. |
  29. | Verification | Checks representative widths, overflow, focus, interaction states, themes, and reduced motion—and limits claims to observed evidence. |
  30. 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.
  31. ## 60-second Quickstart
  32. 1. Install Gridgeist through the primary channel for your agent.
  33. For Codex, add the Git marketplace and install the plugin:
  34. ```powershell
  35. codex plugin marketplace add ohmiler/gridgeist
  36. codex plugin add gridgeist@gridgeist
  37. ```
  38. For Claude Code, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and other compatible agents, use the universal installer:
  39. ```powershell
  40. npx skills add ohmiler/gridgeist -g
  41. ```
  42. **Manual fallback:** If neither installer is available, continue to [Manual installation](#manual-installation).
  43. 2. Start a new agent session in your web project and paste:
  44. ```text
  45. 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.
  46. ```
  47. Agents that support explicit skill invocation can use `$gridgeist` in the prompt. Continue to [Installation](#installation) for product-specific details and more examples.
  48. ## Use cases
  49. - Create a distinctive landing page, dashboard, documentation site, portfolio, or learning platform.
  50. - Redesign an existing interface without breaking its behavior or brand.
  51. - Review a draft and prioritize hierarchy, composition, responsiveness, accessibility, and implementation quality.
  52. - Adapt technical, editorial, image-led, playful, utilitarian, or visible-grid direction without erasing the brand.
  53. ## Installation
  54. ### Codex plugin
  55. This repository is packaged as a Codex plugin through [`.codex-plugin/plugin.json`](.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.
  56. Add the Gridgeist marketplace, then install the plugin:
  57. ```powershell
  58. codex plugin marketplace add ohmiler/gridgeist
  59. codex plugin add gridgeist@gridgeist
  60. ```
  61. Start a new Codex session after installation so the bundled skill is discovered.
  62. ### Universal installer
  63. For Claude Code, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and other compatible agents, install Gridgeist with the [open agent skills CLI](https://github.com/vercel-labs/skills):
  64. ```powershell
  65. npx skills add ohmiler/gridgeist -g
  66. ```
  67. The installer discovers `skills/gridgeist/` and prompts you to choose the target agents. To select one directly, pass its agent name; for example:
  68. ```powershell
  69. npx skills add ohmiler/gridgeist -g -a claude-code
  70. ```
  71. ### Manual installation
  72. Use manual copying only when the plugin and universal installer are unavailable:
  73. ```powershell
  74. git clone https://github.com/ohmiler/gridgeist.git
  75. Copy-Item -Recurse .\gridgeist\skills\gridgeist "$HOME\.agents\skills\gridgeist"
  76. ```
  77. 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.
  78. ## Updating
  79. Gridgeist releases do not update silently. Use the command for the channel that installed the skill, then start a new agent session.
  80. ### Codex plugin
  81. Refresh the Git-backed marketplace snapshot, then reinstall the plugin version exposed by that release:
  82. ```powershell
  83. codex plugin marketplace upgrade gridgeist
  84. codex plugin add gridgeist@gridgeist
  85. ```
  86. 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.
  87. ### Universal installer
  88. Update a global Gridgeist installation:
  89. ```powershell
  90. npx skills update gridgeist -g -y
  91. ```
  92. For a project-scoped installation, use `npx skills update gridgeist -p -y` instead.
  93. ### Git clone or manual copy
  94. 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.
  95. ## Example prompts
  96. Invoke Gridgeist directly with `$gridgeist` and include four essentials:
  97. 1. The product and its audience.
  98. 2. The mode: create, redesign, or review.
  99. 3. What must be preserved, such as behavior, brand color, or content.
  100. 4. What must be verified, such as desktop, mobile, keyboard, and accessibility.
  101. ```text
  102. 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.
  103. ```
  104. ```text
  105. Review this dashboard with $gridgeist. Give me a one-line verdict, prioritized findings with evidence, and a coherent replacement direction before editing.
  106. ```
  107. ```text
  108. Use $gridgeist to create a technical documentation homepage where real API examples and navigation structure carry the visual identity.
  109. ```
  110. ### Brief for a closer match
  111. For a more precise result, provide these details when they are relevant:
  112. - **Product and audience** — what the product does and who uses it.
  113. - **Primary task** — the most important thing the user must accomplish.
  114. - **Direction** — the intended character, such as warm editorial, precise
  115. technical, or playful tactile.
  116. - **Authentic material** — product UI, data, prose, imagery, artwork, code, or a
  117. workflow that should carry visual weight.
  118. - **Preserved constraints** — brand signals, content, routes, behavior, components,
  119. privacy, or platform requirements that must not change.
  120. - **Exclusions** — visual language or behavior that would be wrong for the product.
  121. - **Flows and states** — the important default, loading, empty, error, success,
  122. disabled, and destructive paths.
  123. - **Verification** — representative viewports, keyboard, touch, focus, overflow,
  124. reduced motion, and primary flows to exercise.
  125. When the direction is already clear, state it and let Gridgeist proceed without
  126. another aesthetic questionnaire. When several materially different directions are
  127. still credible, ask Gridgeist to inspect first, offer two or three grounded options
  128. with trade-offs and a recommendation, and wait for alignment before editing.
  129. Copy and adapt this template:
  130. ```text
  131. Use $gridgeist to [create / redesign / review] [page or product surface].
  132. Product and audience:
  133. [What it does and who uses it]
  134. Primary task:
  135. [The most important user outcome]
  136. Direction:
  137. [A confirmed direction, or: Inspect first, propose two or three grounded
  138. directions with trade-offs and a recommendation, and do not edit until I choose.]
  139. Authentic material that should lead:
  140. [Product UI / data / prose / imagery / artwork / code / workflow]
  141. Preserve:
  142. [Brand, content, routes, behavior, components, and constraints]
  143. Avoid:
  144. [Visual language or behavior that would be wrong]
  145. Important flows and states:
  146. [Primary flow and applicable default/loading/empty/error/success/disabled states]
  147. Verify:
  148. [Viewports, keyboard, touch, focus, overflow, reduced motion, and primary flow]
  149. Inspect the repository and rendered interface before taking action.
  150. ```
  151. Describe outcomes and genuine constraints rather than prescribing a CSS recipe.
  152. Unless they are established brand requirements, leave font sizes, spacing, radii,
  153. shadows, and column counts for Gridgeist to derive as one coherent system.
  154. If a project already contains a `DESIGN.md`, theme, token set, or component
  155. library, Gridgeist inspects it alongside the implementation and rendered interface
  156. instead of assuming the sources agree. `DESIGN.md` is optional interoperability,
  157. not a dependency: Gridgeist should not create or update one unless you request a
  158. portable design-system artifact or explicitly include durable system documentation
  159. in the work.
  160. Gridgeist also allows implicit invocation when the agent recognizes a matching web-interface task.
  161. ## Working with companion skills
  162. 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:
  163. ```text
  164. Gridgeist -> Playwright
  165. ```
  166. 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](https://playwright.dev/docs/test-snapshots).
  167. | Situation | Recommended workflow | Division of responsibility |
  168. | --- | --- | --- |
  169. | Most web projects | `Gridgeist -> Playwright` | Design and implementation, then rendered verification |
  170. | 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](https://developers.figma.com/docs/figma-mcp-server/). |
  171. | React or Next.js | `Gridgeist -> Vercel React Best Practices -> Playwright` | Own the interface direction; review framework performance; verify behavior. See [Vercel Agent Skills](https://github.com/vercel-labs/agent-skills). |
  172. | 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](https://github.com/addyosmani/web-quality-skills). |
  173. | Original imagery is required | `Gridgeist -> image generation -> Gridgeist -> Playwright` | Establish the thesis before generating assets, compose with the selected assets, then verify the interface. |
  174. 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.
  175. Example:
  176. ```text
  177. Use $gridgeist to redesign this interface while preserving its behavior and brand.
  178. After implementation, use Playwright to verify representative desktop and mobile
  179. viewports, keyboard interaction, overflow, and the primary user flow.
  180. ```
  181. ## Repository layout
  182. ```text
  183. .codex-plugin/
  184. plugin.json Codex plugin manifest
  185. skills/gridgeist/ Installable skill
  186. SKILL.md Trigger conditions and core workflow
  187. agents/openai.yaml Agent-facing interface metadata
  188. references/ Design language and review checklist
  189. evals/prompts.md Repeatable manual behavior checks
  190. docs/ Design and implementation records
  191. ```
  192. ## Case studies
  193. [Tracefield](https://ohmiler.github.io/tracefield/) applies Gridgeist to a working developer-observability dashboard. Its [repository](https://github.com/ohmiler/tracefield) preserves the generic baseline, exact prompt, evaluation rubric, tested trace domain, and responsive final interface.
  194. [Ledgerline](https://ohmiler.github.io/ledgerline/) tests the same skill on dense payment API documentation. Its [repository](https://github.com/ohmiler/ledgerline) preserves a conventional baseline, exact prompt, six-part rubric, deterministic API content, four viewport checks, and the responsive final interface.
  195. [Morrow](https://ohmiler.github.io/morrow-portfolio/) stress-tests brand adaptation with a fictional image-led creative portfolio. Its [repository](https://github.com/ohmiler/morrow-portfolio) 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.
  196. [Doodlewood](https://ohmiler.github.io/doodlewood/) tests playful interaction design with a fictional, privacy-preserving children's drawing studio. Its [repository](https://github.com/ohmiler/doodlewood) 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.
  197. 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.
  198. ## Limitations
  199. - Output quality depends on the agent inspecting the actual repository and rendered interface.
  200. - Automated checks do not replace visual inspection at representative viewport sizes.
  201. - The suggested defaults are starting points, not a mandatory preset for every brand.
  202. - Model outputs are not deterministic. Re-run evaluations when the skill or target agent changes.
  203. ## Validation
  204. Validate the installable skill structure:
  205. ```powershell
  206. python -X utf8 "$HOME\.codex\skills\.system\skill-creator\scripts\quick_validate.py" .\skills\gridgeist
  207. ```
  208. Check release metadata and bilingual documentation without external dependencies:
  209. ```powershell
  210. python -X utf8 .\scripts\validate_release.py
  211. ```
  212. 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.
  213. ```powershell
  214. python -X utf8 .\scripts\smoke_test_install.py
  215. ```
  216. Behavioral evaluation prompts are in [`evals/prompts.md`](evals/prompts.md).
  217. ## Contributing
  218. 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.
  219. ## License
  220. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.