css-is-awesome 1.1.0

package/scss/examples/_usage.scss

@@ -0,0 +1,317 @@
+// ============================================================================
+// EXAMPLES - Icon Systems + Core Mixins
+// ============================================================================
+@use '../mixins' as m;
+@use '../icons' as i;
+@use '../theme' as t;
+
+// ============================================================================
+// SVG ICONS - Folder Based (No Config Needed!)
+// ============================================================================
+// Just drop .svg files into your $icon-path folder
+// Filename = icon name
+//
+// Folder: /assets/icons/
+//   arrow.svg      → @include i.svg(arrow)
+//   search.svg     → @include i.svg(search)
+//   my-custom.svg  → @include i.svg(my-custom)
+//
+// That's it. No map to update. Just add files and rebuild.
+// ============================================================================
+
+// Basic icons - uses filename directly
+.icon-search { @include i.svg(search); }
+.icon-arrow { @include i.svg(arrow); }
+.icon-menu { @include i.svg(menu, 28px); }
+.icon-close { @include i.svg(close, 20px, m.color(text-muted)); }
+
+// Custom size and color
+.icon-large { @include i.svg(settings, 48px, m.color(brand-primary)); }
+
+// Multi-color SVG (as background, not colorable)
+.logo { @include i.svg-bg(logo, 120px); }
+
+// Icon with text (buttons, links)
+.btn-download { @include i.svg-text(download); }
+.btn-next { @include i.svg-text(arrow-right, $position: after); }
+
+// ALIASING (optional - only when filename ≠ desired name)
+// In _theme.scss:
+//   $icon-svg-alias: (
+//     delete: 'trash',    // @include i.svg(delete) → uses trash.svg
+//     close: 'x',         // @include i.svg(close) → uses x.svg
+//   );
+//
+// Most of the time you don't need aliases.
+// Just name your SVG files what you want to call them.
+
+// ============================================================================
+// FONT AWESOME ICONS
+// ============================================================================
+// Configure $fa-path and $icon-fa-map in _theme.scss
+// Load fonts with @include i.fa-load; in main.scss (if self-hosting)
+
+// Basic FA icon (use inside ::before or ::after)
+.fa-example::before {
+  @include i.fa(check);
+}
+
+// With size
+.fa-large::before {
+  @include i.fa(star, solid, 24px);
+}
+
+// Different styles
+.fa-outline::before {
+  @include i.fa(heart, regular);  // Outline style
+}
+
+.fa-brand::before {
+  @include i.fa(github, brands);  // Brand icon
+}
+
+// FA as standalone element
+.icon-user { @include i.fa-icon(user); }
+.icon-bell { @include i.fa-icon(bell, 20px); }
+.icon-warning { @include i.fa-icon(warning, 24px, solid, m.color(warning-default)); }
+
+// FA icon with text (buttons, links)
+.btn-save { @include i.fa-text(save); }
+.btn-external { @include i.fa-text(external, $position: after); }
+.btn-delete { @include i.fa-text(delete, $size: 0.875em, $gap: 0.5em); }
+
+// Spinning loader
+.loading { @include i.fa-spin(spinner); }
+.loading-large { @include i.fa-spin(spinner, 32px); }
+
+// Adding custom FA icons:
+// 1. Find unicode at https://fontawesome.com/search
+// 2. Add to $icon-fa-map in _theme.scss:
+//    my-icon: '\f123',
+// 3. Use it:
+//    @include i.fa(my-icon);
+
+// ============================================================================
+// REAL COMPONENT EXAMPLES
+// ============================================================================
+
+// Button with SVG icon
+.btn-primary {
+  @include m.btn-base;
+  @include i.svg-text(arrow-right, $position: after);
+  background: m.color(brand-primary);
+  color: m.color(text-inverse);
+  
+  &:hover { background: m.color(brand-primary-hover); }
+}
+
+// Button with FA icon
+.btn-secondary {
+  @include m.btn-base;
+  @include i.fa-text(download);
+  background: transparent;
+  @include m.border;
+  
+  &:hover { background: m.color(interactive-hover); }
+}
+
+// Icon-only button (SVG)
+.btn-icon {
+  @include m.button-reset;
+  @include m.flex($justify: center);
+  @include i.svg(close, 20px);
+  width: 40px;
+  height: 40px;
+  border-radius: m.radius(full);
+  @include m.transition(background-color);
+  
+  &:hover { background: m.color(interactive-hover); }
+}
+
+// Icon-only button (FA)
+.btn-icon-fa {
+  @include m.button-reset;
+  @include m.flex($justify: center);
+  @include i.fa-icon(settings, 20px);
+  width: 40px;
+  height: 40px;
+  border-radius: m.radius(full);
+  @include m.transition(background-color);
+  
+  &:hover { background: m.color(interactive-hover); }
+}
+
+// Alert with FA icon — single-class router pattern (no BEM modifiers).
+// Variant lives in the class name, not as a `--modifier`. The base mixin
+// stays a base; status-specific styling is its own standalone class.
+.alert {
+  @include m.card-base($p: sm);
+  @include m.flex($gap: sm);
+}
+
+.alert-info {
+  background: m.color(info-subtle);
+  @include m.border(3px, solid, info-default, left);
+
+  &::before {
+    @include i.fa(info, solid, 1.25em);
+    color: m.color(info-default);
+  }
+}
+
+.alert-success {
+  background: m.color(success-subtle);
+  @include m.border(3px, solid, success-default, left);
+
+  &::before {
+    @include i.fa(check, solid, 1.25em);
+    color: m.color(success-default);
+  }
+}
+
+.alert-warning {
+  background: m.color(warning-subtle);
+  @include m.border(3px, solid, warning-default, left);
+
+  &::before {
+    @include i.fa(warning, solid, 1.25em);
+    color: m.color(warning-default);
+  }
+}
+
+.alert-error {
+  background: m.color(error-subtle);
+  @include m.border(3px, solid, error-default, left);
+
+  &::before {
+    @include i.fa(error, solid, 1.25em);
+    color: m.color(error-default);
+  }
+}
+
+// Input with icon
+.input-search {
+  position: relative;
+  
+  input {
+    @include m.input-base;
+    padding-left: m.space(xl);
+  }
+  
+  &::before {
+    content: '';
+    position: absolute;
+    left: m.space(sm);
+    top: 50%;
+    transform: translateY(-50%);
+    @include i.svg(search, 20px);
+    color: m.color(text-muted);
+    pointer-events: none;
+  }
+}
+
+// Navbar with icons — single-class child elements, not BEM `__element`.
+// Author-side code names its own classes (`navbar-logo`, `navbar-menu-btn`).
+.navbar {
+  @include m.flex($justify: between);
+  @include m.pad-y(sm);
+  @include m.pad-x(md);
+  @include m.border(1px, solid, border-default, bottom);
+}
+
+.navbar-logo {
+  @include i.svg-bg(logo, 32px);
+}
+
+.navbar-menu-btn {
+  @include m.button-reset;
+  @include i.svg(menu, 24px);
+
+  @include m.tablet {
+    display: none;
+  }
+}
+
+// Social links with FA brands
+.social-links {
+  @include m.flex($gap: md);
+  
+  a {
+    @include m.button-reset;
+    color: m.color(text-secondary);
+    @include m.hover(color, m.color(text-primary));
+    
+    &.github::before { @include i.fa(github, brands, 24px); }
+    &.twitter::before { @include i.fa(twitter, brands, 24px); }
+    &.linkedin::before { @include i.fa(linkedin, brands, 24px); }
+  }
+}
+
+// ============================================================================
+// CORE MIXINS EXAMPLES
+// ============================================================================
+
+// Font - tokens or values
+.heading { @include m.font(bold, xl, tight); }
+.body { @include m.font(reg, base, normal); }
+.custom { @include m.font(semibold, 1.5rem, 1.4, -0.01em); }
+
+// Spacing
+.section {
+  @include m.pad(lg);
+  @include m.flex($direction: column, $gap: md);
+}
+
+// Borders
+.bordered { @include m.border; }
+.underlined { @include m.border(2px, solid, brand-primary, bottom); }
+
+// Breakpoints
+.responsive {
+  @include m.mobile-only { font-size: 14px; }
+  @include m.tablet { font-size: 16px; }
+  @include m.desktop { font-size: 18px; }
+}
+
+// Component bases
+.btn { @include m.btn-base; }
+.card { @include m.card-base; }
+.input { @include m.input-base; }
+.badge { @include m.badge-base; }
+
+// ============================================================================
+// CHEAT SHEET
+// ============================================================================
+
+/*
+SVG ICONS (folder-based):
+  1. Drop file in /assets/icons/ folder
+  2. Use filename as icon name:
+     arrow.svg → @include i.svg(arrow)
+  
+  @include i.svg(name, size?, color?)
+  @include i.svg-bg(name, size?)              → Multi-color SVGs
+  @include i.svg-text(name, size?, gap?, position?)
+  
+  Optional alias (in _theme.scss):
+    $icon-svg-alias: (delete: 'trash')        → delete uses trash.svg
+
+FONT AWESOME:
+  @include i.fa(name, style?, size?)          → Inside ::before/::after
+  @include i.fa-icon(name, size?, style?, color?)
+  @include i.fa-text(name, size?, gap?, style?, position?)
+  @include i.fa-spin(name, size?, style?)
+  @include i.fa-load                          → Load fonts (self-hosted)
+
+FA STYLES:
+  solid   → Filled (default)
+  regular → Outline
+  brands  → Logos (github, twitter)
+
+CORE MIXINS:
+  m.color(name)       m.space(n)            m.radius(size)
+  m.font(type, ...)   m.border(...)         m.elevation(level)
+  m.transition(...)   m.flex($justify, $gap, $direction, ...)
+  m.pad(size)       m.pad-asym(y, x)
+  m.btn-base(...)     m.card-base(...)      m.input-base(...)
+*/

package/scss/main.scss

@@ -0,0 +1,64 @@
+// ============================================================================
+// MAIN - Entry Point
+// ============================================================================
+// This generates the actual CSS output.
+// Import this once at your app's root.
+// ============================================================================
+@use './generator';
+@use './mixins' as m;
+@use './animations';
+@use './animations-utilities';
+@use './utilities';
+
+// ----------------------------------------------------------------------------
+// GENERATE CSS VARIABLES
+// ----------------------------------------------------------------------------
+@include generator.generate-theme;
+
+// ----------------------------------------------------------------------------
+// BASE STYLES (Optional - include what you need)
+// ----------------------------------------------------------------------------
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+body {
+  margin: 0;
+  font-family: m.font-family(primary);
+  font-size: m.font-size(base);
+  line-height: m.line-height(normal);
+  color: m.color(text-primary);
+  background: m.color(surface-default);
+}
+
+// Resets
+@include m.header-reset;
+@include m.form-reset;
+
+// Links
+a {
+  color: m.color(text-link);
+  text-decoration: none;
+  @include m.transition(color);
+  
+  &:hover {
+    color: m.color(text-link-hover);
+  }
+}
+
+// Focus visible
+:focus-visible {
+  outline: 2px solid m.color(border-focus);
+  outline-offset: 2px;
+}
+
+:focus:not(:focus-visible) {
+  outline: none;
+}

package/scss/recipes/README.md

@@ -0,0 +1,110 @@
+# cia Recipes — Format + Authoring Guide
+
+Recipes are cia's framework-agnostic patterns for building components. Each recipe is a single markdown file under `scss/recipes/`. Recipes ship in the npm package and are exposed to AI agents via the MCP server (`list_recipes`, `get_recipe`, `assemble_prompt`).
+
+> **The recipe IS the deliverable.** cia does not ship a component library. Recipes give consumers (and AI agents) the pattern — they generate or copy the component in their own framework + selector vocabulary.
+
+## File naming
+
+- **Real recipes:** `<slug>.md` — kebab-case slug becomes the URL at `/docs/recipes/<slug>` and the MCP `get_recipe(slug)` key
+- **Template / not-renderable:** `_<name>.md` — underscore prefix; catalog page + MCP loader skip these
+
+## Required frontmatter
+
+Every recipe begins with YAML frontmatter:
+
+```yaml
+---
+name: dialog
+description: Accessible modal dialog built on <dialog>.
+category: overlay
+complexity: medium
+cia-version: ">=1.0.0"
+---
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `name` | string | Must match the filename slug |
+| `description` | string | One sentence — what this recipe builds, no more |
+| `category` | enum | One of: `overlay`, `input`, `data`, `navigation`, `feedback`, `layout`, `auth` |
+| `complexity` | enum | One of: `simple`, `medium`, `complex` |
+| `cia-version` | semver range | Minimum cia version this recipe targets |
+
+## Required H2 sections (in this order)
+
+```markdown
+## Use this when
+## Structure (raw HTML)
+## Styling (cia mixins)
+## Interactivity
+## A11y checklist
+## Framework examples
+```
+
+Each section's purpose:
+
+- **Use this when** — 1-3 sentences describing the consumer scenario. If the reader's situation doesn't match, they should bail and look elsewhere.
+- **Structure (raw HTML)** — the markup with `data-cia-recipe` / `data-slot` attributes. Framework-agnostic; consumer adapts to JSX / template / Svelte syntax.
+- **Styling (cia mixins)** — SCSS using `cia.X` mixin calls against consumer-chosen class names, opened with `@use 'css-is-awesome/api' as cia;` (see [Import convention](#import-convention)). Show the minimum to make it work; cross-link to mixin docs for parameter detail.
+- **Interactivity** — native browser behavior first (`<dialog>.showModal()`, popover API, etc.). JS only where the native primitive can't do the job.
+- **A11y checklist** — concrete, testable items. Each item references the WCAG SC or ARIA pattern it satisfies.
+- **Framework examples** — minimum **4 subsections**: React, Vue, Svelte, vanilla (Web Component preferred for vanilla). Each is runnable code, not pseudocode.
+
+## Optional H2 sections
+
+- **Variants** — common adaptations (size, density, position). One sub-block per variant with the styling delta.
+- **Pitfalls** — known gotchas (SSR, browser compat, focus management edge cases). One bullet per pitfall.
+- **Related recipes** — cross-link to other recipes in the catalog.
+
+## Import convention
+
+**Two imports, two jobs.** A recipe's `scss` blocks are component-level styling, so they open with the **zero-emit authoring barrel**:
+
+```scss
+@use 'css-is-awesome/api' as cia;
+```
+
+`/api` forwards the entire mixin + function API and emits **zero CSS** until a mixin is called, which makes it safe inside a `.module.scss` under Next.js CSS Modules pure mode.
+
+- ❌ **Never** `@use 'css-is-awesome'` in a component styling block. That is the emitting bundle — it prints `:root` tokens, resets and base rules, and a top-level `:root` is a hard build error in CSS Modules pure mode.
+- ✅ `@use 'css-is-awesome'` is only correct in a **root/global** stylesheet, where the tokens are emitted exactly once. If a recipe demonstrates a global stylesheet, label the block with a filename comment (`// app/globals.scss`) so the reader can tell which half of the model they're looking at.
+- Some mixins emit at the root themselves — `cia.print-base` emits a `:root` block plus `@page`. They are still imported from `/api`; what changes is *placement*. Say in prose that they belong at the top level of a global stylesheet, never in a component module. See [`print-to-pdf.md`](./print-to-pdf.md) for the worked example.
+- Recipes stay on `/api` on every toolchain, Turbopack included — the barrel works there. Setup notes for Next.js live in the root [`README.md`](../../README.md).
+
+## Code-block standards
+
+- Fenced blocks with language tag — `html`, `scss`, `tsx`, `vue`, `svelte`, `js`
+- Component styling blocks open with `@use 'css-is-awesome/api' as cia;` — see [Import convention](#import-convention)
+- Use the cia mixin API verbatim — never inline raw token values
+- Class names in examples use the convention `my-<thing>` (signals "your selector here") — never `cia-<thing>` (that prefix is library-owned)
+- Each framework example targets a single component, not a full app
+
+## Forbidden in recipes
+
+- ❌ `@use 'css-is-awesome'` (the emitting bundle) in a component styling block — use `css-is-awesome/api`, see [Import convention](#import-convention)
+- ❌ `cia-` class names (that prefix belongs to the library, not consumer code)
+- ❌ BEM (`__element` / `--modifier`) — see [`feedback_no_bem.md`](../../README.md) project rule
+- ❌ Hard-coded `#hex`, `1rem`, `8px` — use `m.color()`, `m.space()`, `m.radius()`
+- ❌ Inline `style=""` for **appearance** — colour, spacing, type, borders. That defeats the cia mixin pitch, and a reader copying it learns the wrong lesson.
+  - ✅ Allowed for **structural layout-neutralising** only, where an element is required by the HTML contract but must not create a box. The canonical case is `<form method="dialog" style="display: contents">` in `dialog.md`: the form has to wrap the buttons for dialog-close to work, but it must not become a layout box. There is no token or mixin involved and no appearance is being set. `validate-recipes` warns on every inline `style=` so each one stays a conscious decision.
+- ❌ Pseudo-code framework examples ("// import your stuff here")
+
+## How a recipe gets rendered + consumed
+
+- **Humans:** The cia website's `/docs/recipes/[slug]` page reads `scss/recipes/<slug>.md`, parses the markdown, renders with syntax highlighting + copy buttons. Catalog page at `/docs/recipes` lists every recipe filtered by category + complexity.
+- **AI agents:** The MCP server exposes `list_recipes`, `get_recipe(slug)`, and `assemble_prompt({ intent: "recipe:<slug>" })`. AI reads the recipe + relevant mixin signatures and generates the consumer's component in their stack.
+
+## Validation
+
+`npm run validate-recipes` (US-01.1.3 in v1.0 EPIC-01) walks `scss/recipes/*.md`, checks frontmatter against the schema, asserts required H2s exist, and verifies no forbidden patterns appear. Wired into CI for v1.0.
+
+## Template
+
+Copy `_recipe-template.md` to `<your-slug>.md` and fill in. The template includes every required section with comments explaining what to write.
+
+## Where to read next
+
+- [`_recipe-template.md`](./_recipe-template.md) — copyable stub
+- [`dialog.md`](./dialog.md) — first shipped recipe; reference example
+- [`../../roadmap/epics/v1-0/EPIC-01-recipes-book.md`](../../roadmap/epics/v1-0/EPIC-01-recipes-book.md) — v1.0 backlog for the first 5 recipes + catalog + MCP exposure