hail-styl

A versatile design system engine for Stylus. Define robust, theme-agnostic design systems with built-in safety and modularity.

Features

• 🛡️ Token Validation — Dedicated token utilities to deliver consistency at scale. Style confidently with reliable checks and alerts.

• 🕹️ Unified Flush Pipeline — Decoupled design logic from CSS emission. Register tokens and rules anywhere, then emit them in a single, clean pass.

• 🌓 Automatic Light/Dark mode — Use a semantic elevation from 0 to 1 to set colors that automatically adapt their lightness to the current scheme.

• 💚 DX-First — Clean APIs for easy interpolation, concatenation, and validation. Integrated error tracing makes debugging a breeze.

• ⚡️ Zero JS Runtime — Pure Stylus magic. No client-side overhead for a fast-by-default experience.

Quick Start

1. Install

npm install -D @mszr/hail-styl

2. Configure

In the design-system.styl auto-imported by your build tool:

@import '@mszr/hail-styl'

dsSetToken('c:brand', rebeccapurple)

3. Flush

In your app.vue or main single-use entry point:

// Emits all CSS variables and rules
dsUseGenerateDeclarationsAtTopLevel()

Documentation

The documentation is split into focused modules to keep things concise and AI-friendly:

1. Principles — The mental model: Registries, Flushing, and Elevation. [get raw]
2. Getting Started — Installation, configuration, and the Flush call. [get raw]
3. Designing — Defining tokens, rules, and the elevation system. [get raw]
4. Styling — Usage in components: Var(), UseToken(), and UI utilities. [get raw]
5. Customizing — Global configuration, presets, and core controls. [get raw]
6. API Reference — A compact, searchable list of every tool in the engine. [get raw]
7. Conventions — Naming conventions for utils, variables, and tokens. [get raw]
8. Integrations — Setup guides for Vite/Nuxt and behaviors worth knowing. [get raw]

AI Assistants

Use these templates to help an AI assistant work with your design system:

• Styling Context — Teach AI to style components with your tokens.
• Design Context — Teach AI to extend your design system.

📺 Demo

Check out the Nuxt Minimal Demo to see hail-styl in action in a real project.