@agimon-ai/po-style-system

Optional Po integration for code-mode design discovery, bounded checks, source-backed renders and disposable interactive story previews with @agimon-ai/po-style-system-tooling, the workspace port of @agimon-ai/style-system.

Code mode

In Po, use the design namespace instead of invoking the CLI. Load codemode-how-to-style-system, call discover({ namespace: 'design' }), then use exec:

const metadata = await design.metadata({ storyPath: 'src/Button.stories.tsx' });
const shot = await design.componentVisual({
  componentName: 'Components/Button',
  appPath: '.',
  storyName: metadata.exports[0].exportName,
});
image(shot);
return { text: shot.text, artifacts: shot.artifacts, warnings: shot.warnings };

The namespace supports shared/app component discovery, CSS classes, themes, story metadata, design checks, report verification, HTML preview builds and story screenshots. Relative namespace paths resolve from the session folder and stay within its admitted checkout. Optional report and HTML output paths write files. Rendering executes trusted workspace source.

Successful componentVisual renders automatically publish saved screenshots in the Style system Activity grid. On web with Author installed, the first thumbnail click copies the exact saved PNG to persistent session artifacts and opens Author for image feedback. Originals stay in session temporary output. Native and Author-absent clicks retain the static image preview. No click rebuilds the story; the heading still opens the story browser. image() is optional for agent inspection. Persistence warnings retain inline images but do not promise a saved tile. Session-output images survive normal close/reload, subject to host temporary-file cleanup, and are not approved design baselines.

The code-mode guide stays pinned and ungated. In Help mode, load help-how-to-style-system for setup, maintenance and troubleshooting.

Design guidance (design-workflow, po-design-principles, po-mobile-design, po-web-design) and the po-designer agent live in the design plugin, selected with --domains design. The domain does not install tooling: select the design runtime layer for the design namespace.

Interactive preview

When this package and @agimon-ai/po-author are both installed, Author shows an Open story preview action. The temporary tab reads the focused .stories.js, .stories.jsx, .stories.ts, or .stories.tsx source, discovers exact named exports, builds only after an explicit action, runs the compiled HTML in an isolated iframe, and retains the composer for source-targeted feedback.

Standalone CLI compatibility

The portable po-design binary also works without Pi, Po, Author, or MCP. Discovery commands delegate to the workspace style-system tooling CLI. Structured commands provide exact story metadata, bounded checks, stale-evidence verification, and explicit preview builds:

po-design metadata --story-path src/Button.stories.tsx
po-design check --target docs/specs/button/design-target.json --report docs/specs/button/design-check.json
po-design verify --report docs/specs/button/design-check.json
po-design preview --app-path . --story-path src/Button.stories.tsx --story-export Playground --output .tmp/button.html

po-style-system remains a compatible alias for po-design. Approval is a human workflow, not a persisted runtime enforcement gate.

Use --workspace <path> when the process working directory is not the admitted project root.

Opt in

Add this package to a layer used by your selected major mode. Include Author when its source preview action is wanted:

layers:
  design:
    packages:
      - '@agimon-ai/po-author'
      - '@agimon-ai/po-style-system'
majorMode:
  design:
    description: Interactive source-backed story design.
    layers: [design]

The package is not added to Po's default distribution mode.

Generated HTML is a preview artifact. AI changes must target the underlying story or component source. Refresh the preview after edits before treating it as visually verified.

Image export

Export PNG, Prepare annotation, and Send to AI render a fresh image from current source through style-system. Users can mark one normalized region or comment on the whole frozen image. The image does not include transient interaction state inside the iframe, and the UI states this limitation instead of presenting it as an exact capture of iframe state.

Security

Preview building executes trusted workspace source on the server. Project, story, and generated artifact paths are realpath-fenced to the admitted workspace. Browser previews use a script-only opaque-origin iframe and a restrictive content security policy. Remote assets are rejected by that policy, so preview assets must be included in the single-file bundle.

Development

pnpm --filter @agimon-ai/po-style-system lint
pnpm --filter @agimon-ai/po-style-system typecheck
pnpm --filter @agimon-ai/po-style-system test
pnpm --filter @agimon-ai/po-style-system build