BB Rab Unified Icons

A policy-aware SVG icon system for product interfaces. The repository combines a consistent icon catalog with an accessibility contract, a read-only UI audit, a conservative codemod, an MCP server, a Codex Skill, reusable Prompt Blocks, automated tests, and a live browser playground.

Open the live Playground

Why this is an engineering system

Replacing labels with icons is not automatically an improvement. A send control in a composer can be safely icon-only; a payment, login, authorization, refund, delete, or final submit control cannot. This project evaluates the action first, then applies one of four modes:

Risk rules always win. Labels such as “Send payment”, “Copy and delete”, and “Confirm send” cannot be auto-migrated.

Related MCP server: Supericons

Icon drawing contract

All bundled icons follow one geometry system:

• Canvas: 24 × 24 viewBox.

• Primary keyline: coordinates 2…22, producing a 20 × 20 safe drawing area.

• Optical safe zone: keep essential detail within 3…21; curves may overshoot a keyline by at most 0.5 when visual centring requires it.

• Stroke: 2, with round caps and round joins.

• Default rendered size: 20px; accepted programmatic range: 8…128px.

• Fill: none; color: currentColor.

• Touch target: at least 44 × 44 CSS pixels, independent of the SVG size.

• No scripts, event attributes, remote resources, embedded raster data, or javascript: URLs.

See the complete icon standard for optical sizing, state, theme, and accessibility rules.

Color tokens and themes

Icons inherit text color instead of embedding brand colors. Recommended tokens:

:root {
  --icon-default: #334155;
  --icon-muted: #64748b;
  --icon-accent: #2563eb;
  --icon-success: #16a34a;
  --icon-warning: #d97706;
  --icon-danger: #dc2626;
  --icon-on-solid: #ffffff;
}

[data-theme="dark"] {
  --icon-default: #e2e8f0;
  --icon-muted: #94a3b8;
  --icon-accent: #60a5fa;
  --icon-success: #4ade80;
  --icon-warning: #fbbf24;
  --icon-danger: #f87171;
}

Use accent for selection and primary actions, muted for passive metadata, semantic colors only for matching states, and --icon-on-solid on filled controls. Never encode success or failure by color alone.

Install and verify

The package is currently distributed from GitHub and is not claimed as an npm registry release.

git clone https://github.com/enjoytime1101-spec/bbrab-unified-icons.git
cd bbrab-unified-icons
npm install
npm run verify

Node.js 20 or newer is required. Runtime code has no external dependency; the official MCP SDK is a development-only interoperability test dependency.

CLI

Audit the included fixture or your own UI source:

npm exec -- bbrab-icons audit ./examples/browser.html --format markdown
npm exec -- bbrab-icons suggest "Send payment"
npm exec -- bbrab-icons render send --size 24 --label "Send message"
npm exec -- bbrab-icons check

Migration is preview-only by default:

cp ./examples/browser.html /tmp/bbrab-icons-example.html
npm exec -- bbrab-icons migrate /tmp/bbrab-icons-example.html

Writing requires both explicit flags and creates a .bbrab-icons.bak backup:

npm exec -- bbrab-icons migrate /tmp/bbrab-icons-example.html --write --confirm

The lightweight scanner intentionally does not pretend to be a complete JSX parser. Complex component factories remain review items.

JavaScript API

import { auditPath, renderIcon, suggestButton } from "bbrab-unified-icons";

const svg = renderIcon("send", { size: 20, label: "Send message" });
const decision = suggestButton("Confirm and send");
const report = await auditPath("./src");

decision.autoMigrate is true only for an exact, single, low-risk action.

MCP server

The read-only MCP server uses the standard newline-delimited JSON-RPC stdio transport. It exposes audit_ui, suggest_button, render_icon, and read_policy; file mutation is deliberately unavailable.

Generic stdio host configuration:

{
  "mcpServers": {
    "bbrab-unified-icons": {
      "command": "node",
      "args": ["/absolute/path/to/bbrab-unified-icons/agent/mcp-server.mjs"]
    }
  }
}

The test suite connects through the official @modelcontextprotocol/sdk client and exercises the handshake, tool discovery, and tool calls.

Skill, Prompt Blocks, and Agent tools

• Codex Skill: skill/bbrab-icon-workflow/

• Audit Prompt Block: prompts/audit.md

• Migration Prompt Block: prompts/migrate.md

• Pull-request review Prompt Block: prompts/review.md

• Function-tool schema: agent/tool-schema.json

Install the Skill into a project without changing global configuration:

mkdir -p .codex/skills
cp -R ./skill/bbrab-icon-workflow .codex/skills/

Then invoke $bbrab-icon-workflow in a compatible agent host.

Development

npm test
npm run check
npm run audit:example
npm run playground

Open http://127.0.0.1:4173/ after starting the playground. Contributions must follow CONTRIBUTING.md.

The Pages workflow publishes this repository only to its default github.io project URL; it does not change or attach any existing product domain.

Verification boundary

Passing the icon audit proves only that controls follow this repository's visual and accessibility policy. It does not prove that a payment, login, refund, publish action, or other business workflow succeeds. Those flows require their own API, data, and end-to-end tests.

License

MIT