{"id":"db6a8373-ff81-494c-8b58-219285cf4bd7","slug":"boxy-design-skill","kind":"skill","name":"boxy-design-skill","summary":"A sharp-edged design system for web pages and AI coding agents.","owner":"avestura","repoUrl":"https://github.com/avestura/boxy-design-skill","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-09-20T20:08:33.000Z","addedAt":"2026-10-21T11:36:06.390Z","logoUrl":"https://avatars.githubusercontent.com/u/9091958?u=613188558cc1bd00eb7ff9384a2547448b439fc0&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["design-media"],"tags":["agents","border-radius","components","components-library","design","design-system","design-systems","square"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-27T01:08:44.495Z","sample":false,"url":"https://conduits.dev/tools/boxy-design-skill","language":"TypeScript","transports":["stdio"],"install":{"npm":"boxy-design"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\n\n```\n+--------------------------------------+\n|  BOXY                     radius: 0  |\n+--------------------------------------+\n```\n\n**A sharp-edged design system for AI coding agents.**\n\nHairline structure, engineering detail, a rationed palette —\nand a linter that fails the build when something drifts.\n\n[Documentation](https://github.avestura.dev/boxy-design-skill/) ·\n[Tokens](https://github.avestura.dev/boxy-design-skill/tokens.html) ·\n[Components](https://github.avestura.dev/boxy-design-skill/components.html) ·\n[Patterns](https://github.avestura.dev/boxy-design-skill/patterns.html)\n\n</div>\n\n---\n\nAsk an agent for a UI and you get the same page every time: rounded cards, a soft\ndrop shadow, a violet gradient, a pill badge. Boxy is a design system packaged as a\nskill, written as constraints rather than suggestions, with a checker that catches\nthe drift.\n\nIn the spirit of [Zed](https://zed.dev), [Stripe](https://stripe.com) and\n[IBM Carbon](https://carbondesignsystem.com).\n\n## Install\n\n**Claude Code** — plugin marketplace, nothing to publish:\n\n```\n/plugin marketplace add avestura/boxy-design-skill\n/plugin install boxy@boxy-design-skill\n```\n\n**npx** — Claude Code, Cursor, Windsurf, AGENTS.md, Copilot:\n\n```bash\nnpx boxy-design init              # Claude Code\nnpx boxy-design init --ai all     # every supported agent\n```\n\n**curl** — no registries at all:\n\n```bash\ncurl -fsSL https://github.avestura.dev/boxy-design-skill/install.sh | sh\n```\n\nThen just ask for UI. The skill triggers on its own; `/boxy` invokes it explicitly.\n\n## Native framework packages\n\nBoxy ships a package for each popular framework, so you (and your agent) use real\ncomponents instead of copying CSS classes:\n\n| Framework | Package |\n|---|---|\n| React 19 | `@boxy-design/react` |\n| Next.js 16 (App Router) | `@boxy-design/next` |\n| Preact 11 | `@boxy-design/preact` |\n| Vue 3.5 | `@boxy-design/vue` |\n| Nuxt 4 | `@boxy-design/nuxt` |\n| Svelte 5 | `@boxy-design/svelte` |\n| Angular 22 | `@boxy-design/angular` |\n| HTMX / any server-rendered HTML | `@boxy-design/htmx` |\n| Elm 0.19 | `@boxy-design/elm` |\n\n```bash\nnpx boxy-design packages     # which one fits this project\n```\n\nThey are not hand-ported. Every package is generated from one component spec\n(`spec/components.json`) that is validated against the stylesheet and the showcase\nmarkup, then tested against the same conformance cases (every enum value, flag and prop combination of\nevery component), so the HTML they render is identical to the design system's. Every component in the\nstylesheet is covered. The interactive widgets (menus, combobox, calendar, kanban, ...) share one\nframework-free behaviour layer, `@boxy-design/behaviors`, that each package starts with one line. `npx boxy-design init` detects your framework and tells\nyour agent which package to use. Details: [`packages/`](packages/README.md).\n\n## The seven axioms\n\nViolating one is a bug, not a style preference.\n\n1. **Radius is zero.** Everywhere, without exception — avatars, badges and toggles\n   included.\n2. **Lines carry structure.** A 1px border before a background change; a background\n   change before a shadow.\n3. **Never blur a shadow.** Depth is a hard offset (`2px 2px 0 0`) or a hairline.\n   No `backdrop-filter`.\n4. **Everything snaps to 4px.** No `13px`, no `0.375rem`.\n5. **Neutrals do the work; accent is rationed.** Under 5% of painted pixels.\n6. **Hierarchy is typographic.** Size, weight, tracking, case and rules — not color.\n7. **Motion is mechanical.** 80–160ms, linear or sharp, no scale or bounce.\n\n## Three modes\n\nOne system, three postures. Identical radius, borders, spacing, type and motion —\nonly section rhythm, display scale, grid columns and substrate visibility change.\n\n| Mode | For | Signature |\n|---|---|---|\n| `blueprint` | Dev tools, infra, technical products | Grid substrate, corner ticks, mono annotations, dense |\n| `industrial` | Dashboards, admin, internal tools | 16 columns, bottom-border fields, heavy tables |\n| `editorial` | Marketing, landing, docs | 72px display type, 160px rhythm, generous air |\n\n```html\n<html data-mode=\"industrial\" data-theme=\"dark\" data-density=\"compact\">\n```\n\n## What you get\n\n```\n.claude/skills/boxy/\n  SKILL.md                     the axioms, modes and routing\n  references/                  18 docs, loaded on demand\n    tokens.md                  every token, every value\n    modes.md                   blueprint / industrial / editorial\n    layout.md                  rails, grids, shells, breakpoints\n    typography.md              scale, labels, numerals, measure\n    color.md                   contrast pairs, semantics, charts\n    components-core.md         16 components, exact specs\n    components-overlays.md     menus, context menus, popovers, drawers\n    components-navigation.md   breadcrumbs, tab variants, trees, TOC\n    components-content.md      code, lists, accordion, prose, avatars\n    components-data.md         tables, tiles, charts, meters, states\n    components-marketing.md    hero, pricing, FAQ, blog, footer, docs\n    components-forms.md        validation, auth, dates, sliders, upload\n    components-ai.md           agent chat, tool calls, approvals\n    icons.md                   the icon set and its drawing rules\n    motion-depth.md            durations, easing, elevation\n    blueprint-details.md       substrate, ticks, annotations\n    accessibility.md           contrast, focus, keyboard, targets\n    anti-patterns.md           what breaks it, and the fix\n  assets/\n    boxy.css                   tokens, reset, utilities, layout primitives\n    boxy-components.css        every component spec, implemented\n    boxy-icons.svg             51 square-capped icons\n    design-tokens.json         W3C DTCG export\n  scripts/\n    boxy-check.mjs             the linter\n```\n\nComponent specs cover buttons, fields, selection controls, tags, cards, tabs and\ntheir contained and vertical variants, modals, drawers, toasts, tooltips, popovers,\nmenus with submenus, context menus, split buttons, navigation, breadcrumbs, tree\nnavigation, accordions, inline code and code blocks, lists, avatars, timelines, data\ntables, stat tiles, charts, meters, spinners, empty and error states, filter bars,\ndate and range pickers, sliders, steppers, segmented controls, file upload, search,\nlayout primitives, resizable panes, comboboxes, multi-selects, colour pickers,\neditable data grids, kanban boards, notification inboxes, heroes, feature grids,\npricing, FAQs, blogs, footers, docs layouts, multi-step forms, validation, auth\nscreens, settings pages, command palettes and AI agent chat - tool calls,\nreasoning, approvals and the composer.\n\nSpecs tell an agent how a component behaves; `boxy-components.css` gives it the\nfinished visuals, with class names that match the specs, so it does not have to\nre-derive a menu or a calendar from prose.\n\n## The linter\n\nGuidance an agent can ignore is decoration.\n\n```bash\nnpx boxy-design check \"src/**/*\"\nnode .claude/skills/boxy/scripts/boxy-check.mjs \"src/**/*\" --strict\n```\n\n```\nsrc/components/Card.tsx\n     8  error  Nonzero border-radius: border-radius: 8px          radius\n     9  error  Shadow with a blur or spread radius: blur 12px     shadow-blur\n    14  warn   Spacing off the 4px scale: padding: 13px (13px)    space\n\n[ FAIL ]  46 files - 2 errors, 1 warning\n```\n\nParses CSS, SCSS, HTML, JSX, TSX, Vue, Svelte and Astro. Zero dependencies,\nNode 18+, exits non-zero on errors.\n\n| Errors | Warnings |\n|---|---|\n| Nonzero radius, rounded utility classes | Spacing off the 4px scale |\n| Shadow blur or spread, `drop-shadow`, `shadow-md` | Font sizes off the type scale |\n| `backdrop-filter`, `filter: blur()`, `text-shadow` | Raw hex outside the token file |\n| `transition: all`, durations over 240ms | Font weights below 400 |\n| Gradient clipped to text | `ease-in-out`, overshoot curves, `scale()` |\n\nSuppress a line with a `boxy-ignore` comment, a region with\n`boxy-ignore-start` / `boxy-ignore-end`, or a file with `boxy-ignore-file`.\n\n## Tokens\n\nTwo layers. **Primitives** (`--bx-n-600`, `--bx-a-500`) are raw values referenced\nonly inside the token file. **Roles** (`--bx-ink-subtle`, `--bx-accent`) are what\ncomponent code uses. Full listing in\n[the token reference](https://github.avestura.dev/boxy-design-skill/tokens.html).\n\n```css\n/* rebrand by overriding roles, never primitives */\n[data-theme=\"light\"] {\n  --bx-accent: #b5252b;\n  --bx-ink-accent: #8e1d22;  /* must clear 4.5:1 on canvas */\n  --bx-focus: #b5252b;\n}\n```\n\nBoth themes ship complete, light is the default, `prefers-color-scheme` is honored\nand a manual `data-theme` always wins. Two densities: comfortable and compact.\n\nAccessibility targets WCAG 2.2 AA as documented guidance — verified contrast pairs,\na 2px offset focus ring, keyboard paths and semantics specified per component.\n\n## Using it without an agent\n\nThe CSS is two normal stylesheets with no build step - tokens and layout first,\ncomponents on top:\n\n```html\n<link rel=\"stylesheet\" href=\"boxy.css\">\n<link rel=\"stylesheet\" href=\"boxy-components.css\">\n```\n\n```bash\nnpx boxy-design css --out src/styles          # both stylesheets + the icon sprite\nnpx boxy-design css --core --out src/styles   # boxy.css only\nnpx boxy-design tokens --out src/tokens       # just the DTCG JSON\n```\n\nOr from the package: `boxy-design/boxy.css`, `boxy-design/boxy-components.css`,\n`boxy-design/boxy-icons.svg`.\n\n## CLI\n\n```\nnpx boxy-design <command> [options]\n\n  init              Install the skill into this project    (default)\n  css               Copy boxy.css, boxy-components.css, boxy-icons.svg\n  tokens            Copy design-tokens.json only\n  packages          Show the native framework package for this project\n  check [paths]     Lint files against the system\n\n  --ai <list>       claude, cursor, windsurf, agents, copilot, or all\n  --dir <path>      Project root\n  --out <path>      Output directory for css / tokens\n  --css             Also drop the stylesheets and icons into the project\n  --core            css: boxy.css only\n  --force           Overwrite existing files\n  --strict          check: treat warnings as errors\n  --json            packages: machine-readable output\n```\n\nNon-Claude targets also get the full reference set in `.boxy/`, so every agent\nreads the same source of truth.\n\n## Contributing\n\n`skills/boxy/` is the single source of truth. `docs/assets/boxy.css` and\n`docs/assets/boxy-components.css` are copies kept in sync by CI — edit the skill\ncopies, not the site copies. The site inlines `boxy-icons.svg` on every page; the\nsmoke test fails if a page is missing an icon.\n\n```bash\nnode skills/boxy/scripts/boxy-check.mjs docs/   # the site must pass clean\nnode cli/test/smoke.mjs                         # installer + linter tests\n```\n\n## Credits\n\nThe accent and semantic ramps are adapted from\n[IBM Carbon](https://carbondesignsystem.com) (Apache-2.0). The structural ideas come\nfrom [Zed](https://zed.dev) and [Stripe](https://stripe.com). Packaging follows the\npattern set by\n[ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill).\n\nFonts: [Inter](https://rsms.me/inter/) and\n[JetBrains Mono](https://www.jetbrains.com/lp/mono/), both SIL Open Font License.\n\n## License\n\nMIT © avestura\n"}