kss-modern 1.6.2 → 1.7.0-beta.0

package/README.md

@@ -1,91 +1,106 @@
 # kss-modern
 
-A modern, KSS-compatible styleguide generator. Parses KSS comment blocks from CSS/SCSS files and generates a static, accessible styleguide with live component previews.
-
-**[Live demo](https://felixranesberger.github.io/kss-modern/)** showing every feature, built from [`demo/content/`](demo/content/).
+A modern, KSS-compatible styleguide generator. Write KSS comments in your CSS or SCSS, and kss-modern turns them into a fast, accessible styleguide with live component previews, dark mode, themes and a built-in accessibility audit.
+
+**[Open the live demo →](https://felixranesberger.github.io/kss-modern/)**
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/welcome-dark.png">
+  <img src="docs/screenshots/welcome.png" alt="A kss-modern styleguide showing the welcome page of the Verdant demo design system">
+</picture>
+
+The demo documents Verdant, a small fictional design system. Its source in [`demo/content/`](demo/content/) is plain CSS, Pug and Markdown, so it doubles as a reference for writing your own styleguide.
+
+<table>
+  <tr>
+    <td width="50%"><img src="docs/screenshots/dashboard.png" alt="A dashboard screen assembled from other sections with insert-markup"></td>
+    <td width="50%"><img src="docs/screenshots/components-dark.png" alt="The project card component in dark mode with a section theme dropdown"></td>
+  </tr>
+  <tr>
+    <td><b>Whole screens from reusable parts.</b> Pull other sections into a page with <code>&lt;insert-markup&gt;</code> and Pug <code>extends</code>.</td>
+    <td><b>Dark mode everywhere.</b> Previews follow the System, Light and Dark toggle through <code>light-dark()</code> tokens.</td>
+  </tr>
+  <tr>
+    <td><img src="docs/screenshots/theme-ocean.png" alt="The pricing pattern rendered in the Ocean preview theme"></td>
+    <td><img src="docs/screenshots/search.png" alt="The global search dialog with fuzzy matches"></td>
+  </tr>
+  <tr>
+    <td><b>Preview themes.</b> Restyle every preview from the header, with an optional stylesheet per theme.</td>
+    <td><b>Instant search.</b> <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>K</kbd> searches titles and descriptions across the whole styleguide.</td>
+  </tr>
+</table>
 
 ## Features
 
 - KSS-compatible comment parsing from CSS/SCSS files
 - Live component previews with modifier variants
-- Theme dropdowns — a global one in the header (`previewThemes` option) and per-section ones (`Themes:`) — switch previews between the default and themed views, optionally loading a stylesheet per theme
-- Pug template support via worker thread pool
-- Color palette and icon gallery documentation
-- Figma embed integration with light/dark theme sync
-- Accessibility auditing (axe-core) and HTML validation, per component or page-wide via `window.kssAudit()` for CI and AI agents
-- Markdown descriptions with custom components (alerts, accordions)
-- Dark mode with three-way toggle (System/Light/Dark)
-- Global search, keyboard navigation, and "Open in Editor" links
-- Watch mode with smart rebuild (only on KSS comment changes)
-
-## Installation
+- Markup from inline HTML, static `.html` files or Pug templates (compiled in a worker thread pool)
+- Reuse markup across sections with `<insert-markup>`
+- Theme dropdowns in the header (`previewThemes` option) and per section (`Themes:`), optionally loading a stylesheet per theme
+- Color palette and searchable icon gallery
+- Markdown descriptions with alerts, accordions, tables and highlighted code
+- Status indicators in the sidebar
+- Figma embeds with light/dark sync
+- Accessibility audit (axe-core) and HTML validation per component, or page-wide via `window.kssAudit()` for CI and AI agents
+- Dark mode with a System/Light/Dark toggle
+- Global search, keyboard navigation and "Open in Editor" links
+- Watch mode that rebuilds only when KSS comments change
+
+## Quick start
 
 ```bash
-npm install kss-modern
+npm install --save-dev kss-modern
 ```
 
-## Quick Start
+Document a component next to its CSS:
+
+```css
+/*
+Button
+
+The main call to action.
+
+.btn--secondary - Secondary action
+.btn--danger - Destructive action
 
-```ts
+Markup: <button class="btn {{modifier_class}}">Save changes</button>
+
+Styleguide 2.1
+*/
+```
+
+Build the styleguide from a small script:
+
+```js
 import { buildStyleguide } from 'kss-modern'
 
 await buildStyleguide({
   mode: 'production',
   outDir: './styleguide',
-  contentDir: './src/sass/',
+  contentDir: './src/css/',
   projectTitle: 'My Design System',
-  theme: '#005075',
+  brandColor: '#005075',
   html: {
     lang: 'en',
     assets: {
-      css: [{ src: '/css/styles.css' }],
+      css: [{ src: 'css/styles.css' }],
       js: [],
     },
   },
 })
 ```
 
-This scans all `.css` and `.scss` files in `contentDir` for KSS comment blocks and generates a complete static styleguide in `outDir`.
+kss-modern scans every `.css` and `.scss` file in `contentDir` and writes a static styleguide to `outDir`.
 
 ## Documentation
 
-- **[Setup Guide](docs/setup.md)** — Installation, configuration reference, watch mode, project structure, and API reference
-- **[Usage Guide](docs/usage.md)** — Writing KSS comments, all available properties (markup, modifiers, colors, icons, Markdown, Figma, status, wrapper, html/body classes, themes, etc.), and styleguide UI features
-- **[Changelog](CHANGELOG.md)** — Version history and release notes
-
-## Basic KSS Example
-
-```scss
-/*
-Button
-
-A basic button component.
-
-.btn--primary - Primary action button
-.btn--outline - Outlined variant
-
-Markup: <button class="btn {{modifier_class}}">Click me</button>
-
-Styleguide 2.1
-*/
-
-.btn { /* styles */ }
-```
-
-## Markup Includes
-
-The `Markup:` field accepts three formats. File paths are resolved relative to `contentDir`.
-
-```scss
-/* Inline HTML */
-Markup: <button class="btn {{modifier_class}}">Click me</button>
-
-/* Static .html file — contents are inlined as-is */
-Markup: templates/components/badge.html
-
-/* Static .pug file — compiled to HTML at build time */
-Markup: templates/components/card.pug
-```
+- **[Getting started](docs/getting-started.md)** covers installation, watch mode and deployment.
+- **[Writing sections](docs/writing-sections.md)** explains the KSS format and every property.
+- **[Markup and templates](docs/markup.md)** covers inline HTML, Pug templates and `<insert-markup>`.
+- **[Configuration](docs/configuration.md)** lists every option and the JavaScript API.
+- **[The styleguide UI](docs/styleguide-ui.md)** describes search, themes, dark mode and the other visitor features.
+- **[Accessibility audit](docs/accessibility-audit.md)** covers the Audit button and `window.kssAudit()`.
+- **[Changelog](CHANGELOG.md)** lists every release.
 
 ## Development
 
@@ -93,7 +108,8 @@ Markup: templates/components/card.pug
 bun install
 bun run build          # Build: Vite (client assets) then Unbuild (Node.js library)
 bun run dev            # Build + run dev server with Deno (watches test-styleguide/ content)
-bun run demo           # Build the public demo into demo-dist/ (DEMO_BASE_PATH sets the served path)
+bun run demo           # Build the public demo into demo-dist/
+bun run demo:screenshots # Rebuild the demo and refresh the README screenshots in docs/screenshots/
 bun run lint           # ESLint
 bun run test           # Vitest unit + integration tests
 bun run release        # Lint + version bump via bumpp

package/dist/node/lib/index.d.mts

@@ -1,309 +1 @@
-interface SectionMeta {
-    modifiers: {
-        name: string;
-    }[];
-}
-
-/**
- * One entry of a section's `Themes:` block — a theme class (or class list, e.g. `.theme-a.compact`)
- * written as in the KSS comment, plus the label shown in the theme dropdown.
- */
-interface ThemeOption {
-    value: string;
-    description: string;
-}
-interface ColorObject {
-    name?: string;
-    color: string;
-    description?: string;
-}
-interface IconObject {
-    name: string;
-    svg: string;
-}
-interface in2Section {
-    id: string;
-    sectionLevel: 'first' | 'second' | 'third';
-    header: string;
-    description: string;
-    hasMarkdownDescription: boolean;
-    /** Compiled markup, rendered in previews and fullpages exactly as it is. */
-    markup: string;
-    /** `markup` formatted for the code views. Set once the markup is compiled. */
-    sourceCode?: string;
-    modifiers: {
-        value: string;
-        description: string;
-    }[];
-    colors?: ColorObject[];
-    icons?: IconObject[];
-    figma?: string;
-    status?: string;
-    wrapper?: string;
-    htmlclass?: string;
-    bodyclass?: string;
-    /** Theme contexts offered by the section's theme dropdown; classes are applied to the preview's <html>. */
-    themes?: ThemeOption[];
-    source: {
-        css: {
-            file: string;
-            line: number;
-        };
-        markup?: {
-            file: string;
-        };
-    };
-    previewFileName: string;
-    fullpageFileName: string;
-}
-interface in2FirstLevelSection extends in2Section {
-    sections: in2SecondLevelSection[];
-}
-interface in2SecondLevelSection extends in2Section {
-    sections: in2Section[];
-}
-
-/** Title + message for a boxed log entry. */
-interface LogBox {
-    title: string;
-    message: string;
-}
-/**
- * Styleguide logger. Intentionally a small, fixed surface so the underlying
- * logging library (currently consola) stays an implementation detail and can
- * be swapped without touching call sites.
- *
- * The message methods are variadic pass-throughs, so a leading message can be
- * paired with an Error/unknown value — `logger.error('Build failed', err)` —
- * and consola renders the error (and its stack) below the message.
- */
-interface Logger {
-    /** Informational message. */
-    info: (message: unknown, ...args: unknown[]) => void;
-    /** Successful operation. */
-    success: (message: unknown, ...args: unknown[]) => void;
-    /** Non-fatal warning. */
-    warn: (message: unknown, ...args: unknown[]) => void;
-    /** Error — a message, an Error/unknown value, or a message followed by one. */
-    error: (message: unknown, ...args: unknown[]) => void;
-    /** Boxed, highlighted message used for grouped summaries. */
-    box: (box: LogBox) => void;
-}
-/**
- * Create a {@link Logger} backed by consola. consola is wrapped rather than
- * exposed directly so consumers depend only on the {@link Logger} contract.
- *
- * Every entry leads with a blue `tag` badge — styled like consola's own
- * WARN/ERROR badges — passed as part of the message so it always sits at the
- * start of the line. (consola's built-in `tag` option is right-aligned by the
- * fancy reporter and scrolls off a wide terminal.)
- */
-declare function createLogger(tag?: string): Logger;
-/** Shared styleguide logger instance. */
-declare const logger: Logger;
-
-/** The styleguide's accent colour: one value, or one per color scheme. */
-type StyleguideBrandColor = string | {
-    light: string;
-    dark: string;
-};
-/**
- * One entry of the header's **Theme** dropdown — an alternative theme context the previews can be
- * shown in, not a color scheme (that is the separate System/Light/Dark toggle).
- */
-interface PreviewTheme {
-    /**
-     * The theme's class or class list — `'theme-midnight'`, `'.theme-midnight.compact'` — added to
-     * the `<html>` of every preview iframe while the theme is selected.
-     */
-    value: string;
-    /** The label shown in the dropdown. */
-    label: string;
-    /**
-     * Stylesheets loaded into a preview while this theme is selected, layered on top of
-     * `html.assets.css` (they are never replaced). Every preview document carries a `<link>` for
-     * each of these from the start — inert until the theme is selected — so switching costs no
-     * request and shows no flash.
-     *
-     * The CSS is keyed on the theme's class list, so a section's `Themes:` entry gets the same
-     * stylesheets as soon as it resolves to the same classes (`.theme-midnight` here and in the
-     * KSS comment); a section theme that matches no configured entry simply loads no extra CSS.
-     */
-    css?: string[];
-}
-/** Every styleguide option except the accent colour, which carries the deprecated `theme` alias. */
-interface StyleguideOptions {
-    mode: 'development' | 'production';
-    outDir: string;
-    contentDir: `${string}/`;
-    projectTitle: string;
-    deactivateDarkMode?: boolean;
-    launchInEditor?: boolean | {
-        rootDir: string;
-    };
-    /** The themes offered by the header's **Theme** dropdown. */
-    previewThemes?: PreviewTheme[];
-    /** @deprecated Renamed to `previewThemes`, to tell it apart from `brandColor`. */
-    themes?: PreviewTheme[];
-    /**
-     * Reload a preview iframe when its theme changes, instead of swapping the theme's classes and
-     * stylesheets into the loaded document.
-     *
-     * Off by default: the in-place swap is instant and keeps the preview's state. Turn it on when a
-     * preview's own JavaScript reads styling at startup — components that measure, canvas/chart
-     * rendering, web components that snapshot tokens on connect — and so needs to run again against
-     * the new theme. A preview is reloaded only when the visitor actually changes a theme, never on
-     * the initial page load.
-     */
-    reloadPreviewsOnThemeChange?: boolean;
-    /**
-     * Let search engines index the generated styleguide.
-     *
-     * Off by default: a styleguide is internal documentation, and its output directory is usually
-     * served from a host that is reachable without being meant for the public. Every build writes a
-     * `robots.txt` into the output root, and every page carries a matching `<meta name="robots">` —
-     * `noindex, nofollow` while this is off, `index, follow` once it is on.
-     */
-    allowSearchEngineIndexing?: boolean;
-    logoSignet?: {
-        href: string;
-    } | {
-        svgContent: string;
-    };
-    html: {
-        lang: string;
-        assets: {
-            css: {
-                type?: 'regular' | 'overwriteStyleguide';
-                src: string;
-            }[];
-            js: {
-                type?: 'regular' | 'overwriteStyleguide';
-                src: string;
-                additionalAttributes?: Record<string, string>;
-            }[];
-        };
-    };
-    plugins?: {
-        ogImage?: (section: in2Section) => string;
-    };
-}
-/**
- * The styleguide configuration. The accent colour is required under one of its two names:
- * `brandColor`, or the deprecated `theme`.
- *
- * `theme` never had anything to do with the preview themes; it is the colour behind
- * `<meta name="theme-color">`, the generated favicons and the styleguide UI's highlight — hence
- * the rename, which also ends its collision with `themes` / `previewThemes`.
- */
-type StyleguideConfiguration = (StyleguideOptions & {
-    brandColor: StyleguideBrandColor;
-    theme?: never;
-}) | (StyleguideOptions & {
-    /** @deprecated Renamed to `brandColor` — this is the accent colour, not a preview theme. */
-    theme: StyleguideBrandColor;
-    brandColor?: never;
-});
-/**
- * A configuration with the deprecated aliases resolved away. Everything past
- * {@link resolveConfiguration} works with this, so no internal code has to know about the old names.
- */
-interface ResolvedStyleguideConfiguration extends StyleguideOptions {
-    brandColor: StyleguideBrandColor;
-    previewThemes: PreviewTheme[];
-}
-/**
- * Resolve the deprecated `theme` / `themes` aliases into `brandColor` / `previewThemes`, warning
- * once per option. Idempotent, so the public entry points can each call it without re-warning.
- */
-declare function resolveConfiguration(config: StyleguideConfiguration | ResolvedStyleguideConfiguration): ResolvedStyleguideConfiguration;
-interface StyleguideBuildOutput {
-    errors?: {
-        overwrittenSectionsIds?: string[];
-    };
-}
-interface MenuSectionMapping {
-    title: string;
-    items: {
-        label: string;
-        href: string;
-        status?: string;
-    }[];
-}
-/**
- * Expensive, parse-derived state computed once and reused across incremental rebuilds.
- * A markup-only edit never changes section structure, so the parsed tree, navigation mappings,
- * and lookups stay valid; only affected sections are recompiled and rewritten.
- */
-interface StyleguideContext {
-    baseDirectory: string;
-    parsedContent: in2FirstLevelSection[];
-    overwrittenSectionsIds: string[];
-    sectionsById: Map<string, SectionMeta>;
-    /** section id -> original (pre-compile) markup, i.e. the compile input */
-    rawMarkupBySection: Map<string, string>;
-    /** section id -> compiled markup that is NOT yet <insert-markup>-resolved (persistent) */
-    compiledRepository: Map<string, {
-        markup: string;
-    }>;
-    /** refId -> ids whose compiled markup embeds <insert-markup>refId</insert-markup> */
-    insertMarkupConsumers: Map<string, Set<string>>;
-    headerHtml: string;
-    searchHtml: string;
-    menuSectionMapping: MenuSectionMapping[];
-    /** section id (second & third level) -> its parsed node */
-    nodeById: Map<string, in2Section>;
-    /** any section id -> the location of its owning second-level section (for preview regen) */
-    ownerLocationById: Map<string, {
-        firstLevelIndex: number;
-        secondLevelIndex: number;
-    }>;
-}
-/**
- * Parse given contentDir and get structured data for further processing
- */
-declare function parseStyleguide(contentDir: StyleguideConfiguration['contentDir']): Promise<{
-    content: in2FirstLevelSection[];
-    overwrittenSectionsIds: string[];
-}>;
-/**
- * Full build: parse, compile every section, and write all fullpage + preview files. Returns the
- * reusable context so the watcher can perform targeted incremental rebuilds afterwards.
- */
-declare function buildAll(input: StyleguideConfiguration | ResolvedStyleguideConfiguration): Promise<{
-    errors: StyleguideBuildOutput['errors'];
-    context: StyleguideContext;
-}>;
-/**
- * Builds the styleguide
- * @param config - The configuration for the styleguide
- */
-declare function buildStyleguide(config: StyleguideConfiguration): Promise<StyleguideBuildOutput>;
-/**
- * Incrementally rebuild only the sections affected by a markup change: recompile their pug
- * (cache-aware), re-resolve <insert-markup>, and rewrite just their fullpage + owning preview files.
- * `changedSectionIds` are the sections whose pug (or a dependency) changed.
- */
-declare function rebuildSections(config: ResolvedStyleguideConfiguration, context: StyleguideContext, changedSectionIds: Iterable<string>): Promise<void>;
-/**
- * What triggered a {@link watchStyleguide} rebuild:
- * - `structural` — a CSS/SCSS/Markdown edit that can change section structure; the whole styleguide is rebuilt.
- * - `markup` — a Pug/HTML edit; only `sections` (those depending on `file`) are rebuilt.
- */
-type StyleguideChange = {
-    type: 'structural';
-} | {
-    type: 'markup';
-    files: string[];
-    sections: string[];
-};
-/**
- * Builds the styleguide and watches for changes
- * @param input - The configuration for the styleguide
- * @param onChange - Optional callback invoked after each rebuild, with the change that triggered it
- * @param onError - Optional callback function to call when an error occurs while building the styleguide
- */
-declare function watchStyleguide(input: StyleguideConfiguration | ResolvedStyleguideConfiguration, onChange?: (change: StyleguideChange) => void, onError?: (errorData: StyleguideBuildOutput['errors']) => void): Promise<void>;
-
-export { buildAll, buildStyleguide, createLogger, logger, parseStyleguide, rebuildSections, resolveConfiguration, watchStyleguide };
-export type { LogBox, Logger, PreviewTheme, ResolvedStyleguideConfiguration, StyleguideBrandColor, StyleguideChange, StyleguideConfiguration, StyleguideContext };
+export { B as BuildAllOptions, L as LogBox, a as Logger, P as PreviewTheme, R as ResolvedStyleguideConfiguration, b as StyleguideBrandColor, c as StyleguideChange, S as StyleguideConfiguration, d as StyleguideContext, e as buildAll, f as buildStyleguide, g as createLogger, l as logger, p as parseStyleguide, r as rebuildSections, h as resolveConfiguration, w as watchStyleguide } from '../shared/kss-modern.Blhbay-v.mjs';