create-halation 0.1.1 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-halation",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Start a new React project with Halation: the styles, the components, and an agent kit that keeps every page on-brand.",
   "license": "MIT",
   "type": "module",

package/template/.claude/settings.json

@@ -1,12 +1,33 @@
 {
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${CLAUDE_PROJECT_DIR:-.}/.halation/hooks.sh\" guard || exit 2"
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Edit|Write|MultiEdit",
         "hooks": [
           {
             "type": "command",
-            "command": "npx --no-install halation lint --hook"
+            "command": "sh \"${CLAUDE_PROJECT_DIR:-.}/.halation/hooks.sh\" lint || exit 2"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${CLAUDE_PROJECT_DIR:-.}/.halation/hooks.sh\" stop || exit 2"
           }
         ]
       }

package/template/.claude/skills/halation/SKILL.md

@@ -5,7 +5,7 @@ description: The Halation design system's rules and React components for this pr
 
 # Halation
 
-This project's look is a set of rules, enforced in code. Build with the components, the ten text styles and the color roles, and the result stays on brand without guessing. `halation lint` and a hook check source as you edit; `halation check` measures the rendered page.
+This project's look is a set of rules, enforced in code. Build with the components, the eleven text styles and the color roles, and the result stays on brand without guessing. `halation lint` and a hook check source as you edit; `halation check` measures the rendered page.
 
 ## Set up
 
@@ -28,7 +28,7 @@ export function App({ children }) {
 - Ink, not color. One accent, spent only where it means something; the main action is ink (R1, R2).
 - Light, not paint. Depth comes from an atmosphere, lit edges and shadows, never decorative gradients (R3, R15).
 - Structure, not strings. Facts get their own lines, states get a word and a shape (R9, R10).
-- Few sizes, plain case. Ten text styles, sentence case, no added tracking (R5, R6, R7).
+- Few sizes, plain case. Eleven text styles, sentence case, no added tracking (R5, R6, R7).
 - Lines before boxes. A hairline or space first; a box only for an object, never a box in a box (R13).
 - Motion explains a change. Under 300 ms, exits faster than enters, nothing moving while idle (R14).
 - Plain words. Sentence case, short labels; errors say what's wrong and how to fix it.
@@ -81,11 +81,11 @@ export function App({ children }) {
 - Do: The text style alone; each one sets its own tracking.
 - Why: Tracking is tuned per size already; extra spacing is how eyebrows get made.
 - Instead: The text style for that size.
-- Caught by: Theme.
+- Caught by: Theme, lint.
 
-### R7: Ten named text styles; no other sizes.
+### R7: Eleven named text styles; no other sizes.
 
-- Don't: `text-sm`, `text-2xl`, `text-[13px]`, `font-size: 15px`.
+- Don't: `text-sm`, `text-2xl`, `text-[13px]`, `font-size: 17px`.
 - Do: `<Text size="body-sm">`, `className="text-body-sm"` (Tailwind) or `hl-text-body-sm`.
 - Why: A small scale is what makes pages feel composed.
 - Instead: The nearest style.
@@ -179,6 +179,46 @@ export function App({ children }) {
 - Instead: The Keys component.
 - Caught by: Lint.
 
+### R19: Tailwind comes through Halation's theme.
+
+- Don't: `@import "tailwindcss"` in your CSS, which brings back Tailwind's whole palette and type scale.
+- Do: `@import "@halation/core/tailwind.css"`, which loads Tailwind with only the system's values.
+- Why: Tailwind's own entry brings back its whole palette, type scale and radii, so off-system classes quietly work again.
+- Instead: @import "@halation/core/tailwind.css", which loads Tailwind with only the system's values.
+- Caught by: Lint.
+
+### R20: Pages look the same to the checker as to people.
+
+- Don't: `if (navigator.webdriver)` or a user-agent test that shows a checker something different.
+- Do: One page for everyone. If a check fails, fix the page.
+- Why: A page that spots the checker and shows it something else hides every problem the check would find.
+- Instead: One page for everyone; fix what the check reports.
+- Caught by: Lint.
+
+### R21: An exception names the rule it breaks.
+
+- Don't: A bare `halation-ignore` comment, or one that names no rule.
+- Do: `/* halation-ignore R9: a real product name uses the dot */`: the rule id, and why.
+- Why: A blanket exception silences every rule on its line, including the ones nobody meant to allow.
+- Instead: An exception needs the rule id it's for, like halation-ignore R9, and a reason.
+- Caught by: Lint.
+
+### R22: No glow on text.
+
+- Don't: `text-shadow: 0 0 24px var(--color-accent)` to make a headline glow.
+- Do: Light behind the text: a `<Stage>` phenomenon with the headline marked `data-quiet`.
+- Why: Glowing text is a generated-design cliché, and it hurts legibility.
+- Instead: Plain text. Light belongs to surfaces and phenomena. The one bloom text may take is the halation phenomenon's, in dark mode, once per page.
+- Caught by: Lint, page check.
+
+### R23: Pages fit a phone: nothing scrolls sideways.
+
+- Don't: A fixed-width row, table or code line that makes a phone scroll sideways.
+- Do: Let rows wrap, give tables and code their own scroll container, and check at 375 px.
+- Why: Most visitors arrive on a phone, and a page that scrolls sideways there feels broken.
+- Instead: Widths that give way: rows that wrap, fluid text styles, a max-width instead of a width.
+- Caught by: Page check.
+
 ## What to use for what
 
 | Need | Use |
@@ -211,13 +251,19 @@ export function App({ children }) {
 | A person | `<Avatar name="..." src={...} />` |
 | An icon | `<icons.CheckIcon />` and the rest, never emoji |
 | The project's mark, credits, share image | `<Seal>`, `<Colophon>`, `<ShareCard>` |
+| Search and jump anywhere (⌘K) | `<Lens>` with `useLensShortcut` |
+| Let people set a keyboard shortcut | `<ShortcutRecorder>` |
+| Pick a time of day | `<Sundial>` |
+| Tune a value by feel | `<Dial>` |
+| Let people pick an accent | `<AccentForge>` |
+| Upload photos or files | `<LightTable>` |
 
 ## Components
 
 All from `@halation/react`.
 
 - **HalationProvider**: Wrap the app once. Sets accent, tempo and theme, hosts tooltips and toasts, and puts on the project's signature. `<HalationProvider name="Lumen" accent="vermilion">{children}</HalationProvider>`
-- **Text**: Any running text, in one of the ten styles (size) with an optional tone: muted, subtle, accent or critical. `<Text size="body-sm" tone="muted">Synced a minute ago</Text>`
+- **Text**: Any running text, in one of the eleven styles (size) with an optional tone: muted, subtle, accent or critical. `<Text size="body-sm" tone="muted">Synced a minute ago</Text>`
 - **Heading**: Headlines. level sets the element and its default style (1 is display-xl, 3 is title-1); size overrides the style. `<Heading level={3}>Storage</Heading>`
 - **Serif**: The one italic serif phrase inside a headline, at title sizes and up (R8). `<Heading level={1}>Every app, <Serif>twice</Serif></Heading>`
 - **Value**: A number with tabular figures and a quieter unit. `<Value unit="MB">412</Value>`
@@ -262,9 +308,18 @@ All from `@halation/react`.
 - **useDevelop**: Develops an element like a print, once per visitor. For a landing hero. `const hero = useRef(null); useDevelop(hero)`
 - **darkroom**: Opens or closes the darkroom inspector from code. `darkroom.enter()`
 - **useDarkroom**: Whether the darkroom is open, for a button that enters and leaves it. `const open = useDarkroom()`
+- **Lens**: A command palette that pulls focus: a lit carriage on the chosen row, the rest softening with distance. For any app with more than a handful of places to go. `<Lens open={open} onOpenChange={setOpen} groups={[{ name: "Copies", items: [{ id: "work", title: "Claude Work", onSelect: openWork }] }]} />`
+- **useLensShortcut**: Opens Lens on ⌘K (Ctrl+K elsewhere). `useLensShortcut(() => setOpen(true))`
+- **ShortcutRecorder**: Records a key combination with keycaps that go down while held. Refuses taken shortcuts and keys with no modifier, in words. Label it with what the shortcut does. `<ShortcutRecorder value={keys} onValueChange={setKeys} label="Switches to Claude Work" onMessage={setNote} />`
+- **TAKEN_SHORTCUTS**: The shortcuts macOS keeps for itself, with the reason for each. Spread it into your own list of taken shortcuts. `taken={{ ...TAKEN_SHORTCUTS, "⌘N": "⌘N makes a new copy." }}`
+- **Sundial**: A time-of-day picker set by moving the sun, showing the real sky for that minute. For schedules and quiet hours; value is minutes after midnight. `<Sundial value={minutes} onValueChange={setMinutes} label="Quiet hours begin at" />`
+- **LitTabs**: Tabs whose selection is a carriage of light; labels gain weight as it passes. Use for a page's main sections. `<LitTabs aria-label="Sections" items={[{ value: "all", label: "Overview", content: <Overview /> }]} />`
+- **Dial**: A rotary knob with detents that click, lit ticks and a rolling number. For intensity, volume, zoom: a value tuned by feel. `<Dial value={level} onValueChange={setLevel} label="Intensity" />`
+- **AccentForge**: An accent picker that derives every accent role from a hue and shows each pair's contrast in both modes. Purple hues are closed. `<AccentForge hue={hue} onHueChange={setHue} />`
+- **LightTable**: A file drop zone that backlights under the dragged file; dropped photos land as prints that develop. For uploads, avatars and imports. `<LightTable onFiles={upload} />`
 - **icons**: The system's glyphs: CheckIcon, PlayIcon, WrenchIcon, StopIcon, PencilIcon, InfoIcon, AlertIcon, ChevronIcon, CloseIcon. Use these or a real icon set, never emoji. `<icons.CheckIcon />`
 
-## The ten text styles
+## The eleven text styles
 
 Use `<Text size>`, `<Heading size>`, `hl-text-<name>`, or `text-<name>` in Tailwind. No other sizes.
 
@@ -277,6 +332,7 @@ Use `<Text size>`, `<Heading size>`, `hl-text-<name>`, or `text-<name>` in Tailw
 | title-3 | 20 px | Card and group titles. |
 | body-lg | 18 px | Lead paragraphs under a headline. |
 | body | 16 px | Reading text. |
+| control | 15 px | Labels on tabs, keycaps and segmented controls. |
 | body-sm | 14 px | Interface text: controls, lists, tables. |
 | caption | 13 px | Metadata, helper text, footnotes. |
 | micro | 12 px | Badges, keyboard keys, counters. Never sentences. |

package/template/.halation/hooks.sh

@@ -0,0 +1,34 @@
+#!/bin/sh
+# Halation's hooks for Claude Code, written by halation init. Takes guard, lint or stop.
+cd "${CLAUDE_PROJECT_DIR:-.}" || exit 2
+input=$(cat)
+run() {
+  if [ -x node_modules/.bin/halation ]; then printf '%s' "$input" | node_modules/.bin/halation "$@"; return $?; fi
+  if npx --no-install halation --version </dev/null >/dev/null 2>&1; then printf '%s' "$input" | npx --no-install halation "$@"; return $?; fi
+  return 127
+}
+case "$1" in
+  guard) run guard --hook ;;
+  lint) run lint --hook ;;
+  stop) run lint --stop ;;
+  *) echo "hooks.sh takes guard, lint or stop." >&2; exit 2 ;;
+esac
+status=$?
+[ "$status" -eq 0 ] && exit 0
+[ "$status" -ne 127 ] && exit 2
+case "$1" in
+  guard)
+    printf '%s' "$input" | grep -Eq '"command"[[:space:]]*:[[:space:]]*"(npm|pnpm|yarn|bun)[[:space:]]+(install|i|ci|add)([[:space:]"]|$)' && exit 0
+    echo "Halation isn't installed in this project yet, so changes are blocked until it is. Install the project's dependencies first, with npm install or your package manager's install." >&2
+    exit 2 ;;
+  stop)
+    if printf '%s' "$input" | grep -Eq '"stop_hook_active"[[:space:]]*:[[:space:]]*true'; then
+      echo '{"systemMessage": "Halation is not installed, so the design rules were not checked before this turn ended."}'
+      exit 0
+    fi
+    echo "Halation isn't installed, so the design rules can't be checked. Install the project's dependencies, then finish." >&2
+    exit 2 ;;
+  *)
+    echo "Halation isn't installed, so this change wasn't linted. Install the project's dependencies." >&2
+    exit 2 ;;
+esac

package/template/AGENTS.md

@@ -21,7 +21,7 @@ Run `pnpm build` before you call a change done. TypeScript must pass with no err
 - Sentence case everywhere. No uppercase labels and no letter-spaced eyebrows.
 - Facts go in `Facts` or on separate lines. Never join them with `·`, `•` or a bar.
 - Show a state with `State`, never a colored dot.
-- Text comes in ten styles: `display-xl`, `display`, `title-1`, `title-2`, `title-3`, `body-lg`, `body`, `body-sm`, `caption` and `micro`. Use `Text`, `Heading` or the `hl-text-*` classes, not other sizes.
+- Text comes in eleven styles: `display-xl`, `display`, `title-1`, `title-2`, `title-3`, `body-lg`, `body`, `control`, `body-sm`, `caption` and `micro`. `control` is for labels on tabs, keycaps and segmented controls. Use `Text`, `Heading` or the `hl-text-*` classes, not other sizes.
 - Colors come from the tokens (`var(--color-fg)`, `var(--color-accent)` and the rest), never from literal values.
 - No gradients as decoration. Depth comes from the phenomenon on the `Stage`, lit edges and shadows.
 - One ink button per view: the main action. Everything else is secondary or ghost.

package/template/package.json

@@ -11,12 +11,12 @@
     "check": "halation check http://localhost:5173"
   },
   "dependencies": {
-    "@halation/react": "^0.1.1",
+    "@halation/react": "^0.2.1",
     "react": "^19.3.0",
     "react-dom": "^19.3.0"
   },
   "devDependencies": {
-    "@halation/cli": "^0.1.1",
+    "@halation/cli": "^0.2.1",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.7",
     "@vitejs/plugin-react": "^6.1.1",