Communitygithub.com

halo-design

Design skill. Halo, a calm, glossy, numbers-first design system for any web app, dashboard, tool, landing page or vector PDF, bilingual by design (English + Kurdish Sorani or any RTL script). Use it when the user asks for the Halo style, wants a polished dark/light interface that feels alive (rim-lit cards, quiet motion, optional calm sound), needs Kurdish, Arabic or Persian alongside English, or wants print-ready vector PDFs. The agent writes a short design brief and invents a product-specific signature visu

What is halo-design?

halo-design is a Claude Code agent skill that design skill. Halo, a calm, glossy, numbers-first design system for any web app, dashboard, tool, landing page or vector PDF, bilingual by design (English + Kurdish Sorani or any RTL script). Use it when the user asks for the Halo style, wants a polished dark/light interface that feels alive (rim-lit cards, quiet motion, optional calm sound), needs Kurdish, Arabic or Persian alongside English, or wants print-ready vector PDFs. The agent writes a short design brief and invents a product-specific signature visu.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/SawabS/halo-design-skill/tree/HEAD

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Halo design skill

Halo is a way of designing, not a theme to copy. It fixes the grammar (tokens, type, motion, accessibility, bilingual layout, QA) and leaves the product's character to you: its signature visual, accent meanings, illustrations, copy and sound. The workout plan in examples/ and the two templates are demonstrations of the mechanics, not content to reuse.

Ground rules

  1. Design per product. Write the brief first (templates/brief.md) and choose a signature visual that fits this product (docs/00-creative-direction.md). Rings, exercise pictograms and workout copy are wrong unless the product is about closing daily goals.
  2. Platform → Halo → proven library. Never invent mechanisms (docs/16-libraries.md).
  3. Tokens are the only source of colour, curve and radius. No colour literals outside tokens/tokens.css; scripts/check_skill.py enforces this for Halo's CSS.
  4. Both themes, both directions, every breakpoint are designed and tested.
  5. Numbers first: grey label → big accent value → plain sentence. Visuals repeat the number, never replace it.
  6. Motion is light: one curve, reveal once, nothing loops, reduced-motion safe. Live data updates in place and never re-animates.
  7. No logos. The brand slot is the product's name in text. Use a mark only if the user supplies one.
  8. Done means QA passed (docs/13-qa.md).

Read only what the task needs

The docs are short (under 1,500 tokens each). Don't read everything; route by task:

TaskReadStart from
Any new product or pagedocs/00, docs/02, docs/03, docs/05templates/starter.html (personal app) or templates/dashboard.html (data / ops)
Data-heavy screendocs/10, docs/04templates/dashboard.html
Kurdish / Arabic / Persiandocs/08, docs/03either template with lang=ckb
Phone polishdocs/07—
Motion, rim light, scrolldocs/06—
Sounddocs/14js/halo-sound.js
Icons or illustrationsicons/README.md, docs/09icons/
Printed document or PDFdocs/11templates/print-a4.html
React / Next / Tailwind / Vuedocs/17—
Choosing a librarydocs/16—
Figma or design tokens for other toolsdocs/15, tokens/*.tokens.json—
Accessibilitydocs/12—
Testingdocs/13qa/

Never read examples/workout-plan/index.html whole (about 42k tokens). Search it for a specific pattern instead (grep -n "restTimer" …).

Workflow

  1. Brief. Fill in templates/brief.md: who it's for, what they come back to check, the 1–3 hero numbers, the signature visual, accent meanings, illustration language, motion and sound intensity, surfaces, languages and sections. If the request is ambiguous, show the brief and ask one question; otherwise state it in a short paragraph and build.
  2. Foundation. Link tokens/tokens.css, css/halo.css, js/halo.js (plus js/halo-sound.js only if the brief has sound), and call Halo.init({dict}). Fonts: Google Sans + IBM Plex Sans Arabic (docs/03).
  3. Compose sections from the components in docs/05:
    • Build the signature visual with existing pieces: Halo.rings, Halo.spark, .meter with a .target marker, .bars, .timeline, the status grid, or a typographic hero. Or invent one that follows the rules in docs/00.
    • Replace all template content. If your page says "Close the rings" or "GPUs healthy" and the product isn't about that, you copied.
  4. Balance phone and laptop separately (docs/04, docs/07).
  5. Bilingual: every string goes in the dictionary, with RTL rules from docs/08. If you write Kurdish yourself, tell the user and recommend a native review.
  6. Motion and sound at the intensity the brief chose (docs/06, docs/14).
  7. QA, served over http:
    python3 qa/qa_layout.py http://localhost:8000/page.html    # 9 widths × 2 themes × 2 languages
    python3 qa/qa_touch.py  http://localhost:8000/page.html    # phone touch suite
    
    Add the product's own interaction checks and axe-core. Review screenshots at 390 and 1440 in both themes.
  8. Print if needed: HTML → scripts/print_pdf.py → qpdf merge → scripts/verify_pdf.sh (0 images). Embed .ttf fonts.

Pre-delivery checklist

  • A brief exists, and the signature visual fits the product (not rings by default, not copied content).
  • At most three accent meanings, used consistently; text accents use --XT.
  • No colour literals outside tokens; no logo the user didn't supply.
  • Laptop: balanced columns, aligned footers, charts fill their cards. Phone: ≤ 4 nav controls, 44 px targets, no sideways scroll at 320.
  • RTL: dir/lang, flipped chevrons, mirrored charts, <bdi> around Latin terms and Latin units.
  • Reduced motion honoured; sound (if any) has a toggle and is never the only signal.
  • Sources linked for factual claims; Undo for destructive actions.
  • qa_layout.py and qa_touch.py pass; no console errors; PDFs verified vector.

Reproducibility

  • make setup installs pinned dependencies (requirements.txt) and Chromium.
  • make check validates the skill itself: links, tokens in sync, no stray colours, no logos, JS syntax, frontmatter.
  • make qa tests every template and the example; make assets re-renders the README images; make tokens rebuilds the DTCG JSON.
  • CI runs the same in .github/workflows/qa.yml.

File map

PathWhat
docs/00-creative-direction.mdRead first. Brief, signature visual catalogue, accent meanings, illustration language, anti-patterns
templates/brief.mdThe brief to fill in
templates/starter.htmlPersonal-app mechanics: split hero, rings, tasks, timer, sheet, sound
templates/dashboard.htmlData/ops mechanics: status grid, sparklines, meters with targets, live updates, still motion
templates/print-a4.htmlVector print page
tokens/tokens.css (source of truth) + DTCG 2025.10 JSON
css/halo.css · js/halo.js · js/halo-sound.jsComponents · runtime · calm sound
icons/UI icons (Lucide grid), glyphs, pictogram grammar + gallery
docs/01–17Principles, colour, type, layout, components, motion, phone, RTL, icons, data viz, print, a11y, QA, sound, Figma, libraries, frameworks
qa/ · scripts/Test suites · print, verify, tokens, assets, self-check
fonts/IBM Plex Sans Arabic + Inter (TTF, OFL) for offline, CI and print
examples/workout-plan/One complete product made with Halo (site + 4 vector PDFs). Reference only.

Related Skills