@threadlabs/looma-docs 0.0.0-stage → 0.52.0

package/docs/guides/04.theme-decisions.md

@@ -0,0 +1,141 @@
+---
+title: Theme decisions
+order: 4
+---
+
+<div data-looma-guide>
+
+# Theme decisions
+
+A theme starts with decisions such as “forest green actions,” “serif headings,” and “roomier controls.” Looma turns those decisions into shared CSS properties that your components use.
+
+You can make those decisions in **Customize**, or edit the JSON recipe and regenerate the CSS. This guide follows one decision through that process, then maps each family in detail.
+
+## Follow a decision from recipe to component
+
+<link rel="component" href="@threadlabs/looma/components/ui-grid/ui-grid.html">
+<link rel="component" href="@threadlabs/looma/components/ui-card/ui-card.html">
+<link rel="component" href="@threadlabs/looma/components/ui-stack/ui-stack.html">
+<link rel="component" href="@threadlabs/looma/components/ui-text/ui-text.html">
+
+<ui-card padding="md">
+<ui-grid columns="3" min="sm" gap="l">
+  <ui-stack gap="s">
+    <ui-text variant="eyebrow" tone="muted">01 · Decide</ui-text>
+    <ui-text variant="heading" as="h3">A roomier control</ui-text>
+    <ui-text variant="code" size="sm" wrap="anywhere">control-roominess: 2.75</ui-text>
+    <ui-text variant="caption" tone="secondary">Keep the choice in your JSON recipe.</ui-text>
+  </ui-stack>
+  <ui-stack gap="s">
+    <ui-text variant="eyebrow" tone="muted">02 · Derive</ui-text>
+    <ui-text variant="heading" as="h3">One size family</ui-text>
+    <ui-text variant="code" size="sm">16px × 2.75 = 44px</ui-text>
+    <ui-text variant="caption" tone="secondary">Generate CSS inputs and the rules that derive related sizes.</ui-text>
+  </ui-stack>
+  <ui-stack gap="s">
+    <ui-text variant="eyebrow" tone="muted">03 · Apply</ui-text>
+    <ui-text variant="heading" as="h3">Components agree</ui-text>
+    <ui-text variant="code" size="sm">size="md"</ui-text>
+    <ui-text variant="caption" tone="secondary">A medium button and medium input use the same height family.</ui-text>
+  </ui-stack>
+</ui-grid>
+</ui-card>
+
+::: table
+
+- Step: 1. Choose the intent
+  Example: “Make controls a little roomier.”
+  Where it lives: **Size & spacing → Control roominess** in Customize.
+
+- Step: 2. Keep the decision
+  Example: `"control-roominess": "2.75"`
+  Where it lives: `values` in `looma.theme.json`.
+
+- Step: 3. Generate the CSS
+  Example: `--ui-control-roominess: 2.75;`
+  Where it lives: `looma.theme.css`, alongside the shared derivation rules.
+
+- Step: 4. Derive the family
+  Example: A 16px text base gives a 44px medium control; the size ratio derives small and large.
+  Where it lives: Shared CSS roles such as `--ui-control-size-md`.
+
+- Step: 5. Use the result
+  Example: A medium button and medium input take their height from the same family.
+  Where it lives: Looma's component definitions, and your components when they use those public roles.
+
+:::
+
+The JSON keeps **what you chose**. The CSS carries **what the application renders**. Commit both, so you can reopen the customizer and reproduce the result.
+
+## Read the two files together
+
+This is a small recipe with explicit choices. Omitted values use the generator's defaults; a starting theme supplies a fuller set.
+
+```json
+{
+  "schemaVersion": 1,
+  "values": {
+    "text-size": "16px",
+    "control-roominess": "2.75",
+    "scale-contrast": "1.2",
+    "display-font": "Georgia, serif",
+    "response-time": "150ms"
+  }
+}
+```
+
+The generated stylesheet includes these authoring properties:
+
+```css
+:root {
+  --ui-font-size: 16px;
+  --ui-control-roominess: 2.75;
+  --ui-scale-ratio: 1.2;
+  --ui-font-display: Georgia, serif;
+  --ui-motion-fast: 150ms;
+}
+```
+
+That excerpt is only the input layer. The saved CSS also includes light and dark colors and the derivation rules for sizes, type, spacing, and material. Use the complete exported file in your application.
+
+## Choose the family you want to understand
+
+- [Color](/theme-colors/): brand seeds, light/dark palettes, semantic statuses, and readable foregrounds.
+- [Typography](/theme-typography/): body and heading fonts, base size, labels, and emphasis.
+- [Size & spacing](/theme-spacing/): control height, the size ladder, rhythm, gaps, corners, and borders.
+- [Material & light](/theme-material/): depth, reflection, transparency, and the light source.
+- [Motion](/theme-motion/): feedback duration, easing, and reduced motion.
+
+Each page connects recipe keys to CSS properties and the result you can see. The [token guide](https://threadlabs.studio/looma/tokens/) explains how to use public properties in your own component styles. The [theme reference](https://threadlabs.studio/looma/theme-reference/) lists the complete property defaults and ranges.
+
+## Color has an extra generation step
+
+A geometry decision such as `control-roominess` becomes a CSS property that the shared rules can use directly. A color decision can affect many resolved properties at once.
+
+For example, an `action` seed contributes to the accent family, readable text on a solid action, contextual action text, and interaction states. `warmth` changes how the palette is generated; it has no matching `--ui-warmth` property. Edit that decision in the recipe or customizer, then regenerate.
+
+See [Color](/theme-colors/) for the full path from seeds to usable roles.
+
+## Use the theme in your own components
+
+Choose semantic roles for what the element means. A reading surface can use `--ui-surface-raised` and `--ui-text-primary`; supporting copy can use `--ui-text-secondary`. The generated palette supplies the right values for light and dark.
+
+```css
+.reading-note {
+  background: var(--ui-surface-raised);
+  color: var(--ui-text-primary);
+  border: var(--ui-border-width) solid var(--ui-border);
+  border-radius: var(--ui-radius-md);
+}
+```
+
+Put that CSS in your own HTML Next definition. Compose Looma controls through their props and supported public properties, so their shared layout and behavior stay consistent.
+
+## Keep the right source editable
+
+- Change the recipe in Customize, save it, and load the generated CSS in your application.
+- Put handwritten adjustments in a separate overrides file.
+- Re-save the recipe after a Looma upgrade to adopt updated generation rules.
+- Use `data-theme="light"` or `data-theme="dark"` for a fixed mode, or leave it off the root to follow the system.
+
+</div>

package/docs/guides/05.(Theme reference)/01.theme-colors.md

@@ -0,0 +1,95 @@
+---
+title: Color
+order: 1
+---
+
+<div data-looma-guide>
+
+# Color
+
+Choose the colors your product starts from. Looma derives the related roles that buttons, fields, text, surfaces, and statuses need in light and dark.
+
+## From a brand seed to usable colors
+
+```text
+Action seed + canvas + surface + text
+                ↓
+Palette relationships and readability checks
+                ↓
+Light and dark semantic roles
+                ↓
+Action fills, labels, links, focus, selection, and statuses
+```
+
+`action` is a starting pigment. The generator chooses readable on-fill text separately and resolves contextual text and interaction states against their surfaces. A seed may be adjusted when needed for readability.
+
+## Start with four seeds
+
+::: table
+
+- Recipe key: `action`
+  Public CSS role: `--ui-accent`
+  What you see: The primary action family, with readable labels and states derived separately.
+
+- Recipe key: `canvas`
+  Public CSS role: `--ui-surface`
+  What you see: The page's ground behind its content surfaces.
+
+- Recipe key: `surface`
+  Public CSS role: `--ui-surface-raised`
+  What you see: Cards, fields, and floating content surfaces.
+
+- Recipe key: `text`
+  Public CSS role: `--ui-text`
+  What you see: The starting text color; usable primary and supporting text roles are derived against surfaces.
+
+:::
+
+```json
+{
+  "schemaVersion": 1,
+  "values": {
+    "action": "#315c48",
+    "canvas": "#faf8f1",
+    "surface": "#ffffff",
+    "text": "#29382e"
+  }
+}
+```
+
+These are the seed choices used in [Fellowship UI](https://github.com/threadlabs-studio/looma/tree/main/examples/fellowship-ui). The generated colors can differ from the seeds to keep the finished roles readable.
+
+## Refine relationships
+
+These keys guide palette generation. They live in the recipe; there is no CSS property with the same purpose to turn later.
+
+::: table
+
+- Recipe keys: `warmth`, `color-intensity`, `palette-relationship`
+  Decision: Cool or warm paper and ink, quiet or vivid color, and how quiet surfaces relate to the brand.
+
+- Recipe keys: `secondary-action`, `tertiary-action`
+  Decision: Optional supporting brand families. Components expose them as `tone="accent-secondary"` and `tone="accent-tertiary"`; omitted accents follow primary.
+
+- Recipe keys: `neutral-source`, `neutral-strength`, `neutral-border-contrast`
+  Decision: Where neutral pigment comes from, how strongly it fills controls, and the minimum boundary contrast shared by neutral actions and fields.
+
+- Recipe keys: `status-chroma`, `success-source`, `danger-source`, `warning-source`, `info-source`
+  Decision: Status saturation and whether each status keeps a semantic hue, harmonizes toward primary, or uses a brand family.
+
+- Recipe keys: `selection-accent`, `focus-accent`, `link-accent`
+  Decision: Which brand family speaks through selected rows, keyboard focus, and inline links.
+
+:::
+
+Warmth and color intensity use 0.5 as their original-seed midpoint. Palette relationship preserves seed hues, relates quiet surfaces to neighboring hues, or uses complementary hues. Neutral fill strength and boundary contrast remain separate decisions. Status relationships change the palette, while words and icons continue to carry status meaning.
+
+## Use semantic roles in components
+
+Choose the role for the job: `--ui-text-primary` for readable content, `--ui-text-secondary` for supporting text, and `--ui-control-border` for the shared neutral control boundary. A semantic role carries the theme's light/dark result and the intended relationship to nearby surfaces.
+
+Every exported theme contains both modes. Set `data-theme="dark"` on a region to give that subtree a dark palette, including inside a light page. A floating surface needs to retain the mode of the region it came from.
+
+[Back to Theme decisions](/theme-decisions/) · [Next: typography](/theme-typography/)
+
+</div>

package/docs/guides/05.(Theme reference)/02.theme-typography.md

@@ -0,0 +1,73 @@
+---
+title: Typography
+order: 2
+---
+
+<div data-looma-guide>
+
+# Typography
+
+Set the shared reading voice, then decide whether headings need their own face. Type roles keep headings, labels, captions, and body text related across components.
+
+## Map your decisions
+
+::: table
+
+- Recipe key: `body-font`
+  CSS property: `--ui-font-sans`
+  What changes: Body text and the shared interface typeface used by controls.
+
+- Recipe key: `display-font`
+  CSS property: `--ui-font-display`
+  What changes: Heading and display text.
+
+- Recipe key: `text-size`
+  CSS property: `--ui-font-size`
+  What changes: The document's px text base. Type, geometry, and spacing derive their rem relationships from it once.
+
+- Recipe key: `label-size`
+  CSS property: `--ui-field-label-font-size`
+  What changes: Field labels. `inherit` follows the body size; a separate length makes labels independent. Help text stays supporting text.
+
+- Recipe key: `text-weight`
+  CSS property: `--ui-font-medium`
+  What changes: Shared emphasis such as control labels, while body and headings retain their roles.
+
+:::
+
+## Try a body and heading pair
+
+```json
+{
+  "schemaVersion": 1,
+  "values": {
+    "body-font": "system-ui, sans-serif",
+    "display-font": "Georgia, serif",
+    "text-size": "16px",
+    "label-size": "inherit"
+  }
+}
+```
+
+This pair uses an operating-system interface face and a serif heading stack. A font stack selects fonts already available to the application. Load custom or self-hosted faces in the application itself.
+
+In Customize, a Google Fonts selection previews the real face and includes its import in the saved CSS. The recipe's optional `fonts` mapping keeps the selected Google family names; `values` keeps the matching CSS stacks. Export and import preserve both.
+
+## Separate meaning from appearance
+
+```html
+<ui-text variant="display" as="h1">The field guide</ui-text>
+<ui-text variant="heading" as="h2">Before you begin</ui-text>
+<ui-text variant="body">A practical introduction for your team.</ui-text>
+<ui-text variant="caption" tone="muted">Updated this week</ui-text>
+```
+
+`variant` chooses a visual role. `as` chooses the document element. You can use a heading's appearance at the appropriate heading level without changing its place in the document outline.
+
+## Check the result
+
+Compare a full heading, a paragraph, a field label, and supporting text together. Then check a medium button beside a medium field. A larger text base also changes the size relationships explained in [Size & spacing](/theme-spacing/).
+
+[Back to Theme decisions](/theme-decisions/) · [Next: size and spacing](/theme-spacing/)
+
+</div>

package/docs/guides/05.(Theme reference)/03.theme-spacing.md

@@ -0,0 +1,103 @@
+---
+title: Size & spacing
+order: 3
+---
+
+<div data-looma-guide>
+
+# Size & spacing
+
+Control height, surrounding space, and vertical rhythm are related decisions with separate jobs. Set the shared family once, then use component size and layout props to compose it.
+
+## Follow a control height
+
+With an explicit 16px text base and a size ratio of 1.2:
+
+::: table
+
+- Decision: Control roominess `2.5`
+  Small: About 33.3px
+  Medium: 40px
+  Large: 48px
+
+- Decision: Control roominess `2.75`
+  Small: About 36.7px
+  Medium: 44px
+  Large: 52.8px
+
+:::
+
+The relationship is `medium = base text size × roominess`, `small = medium ÷ size ratio`, and `large = medium × size ratio`. These values describe the shared height roles. Content, borders, and component-specific constraints can still require more room.
+
+```text
+text-size: 16px        control-roominess: 2.75
+            ↘          ↙
+             medium: 44px
+              ↙       ↘
+ small: 44 ÷ 1.2     large: 44 × 1.2
+```
+
+A 44px example is the result of these chosen values. Choose the proportions appropriate to your interface. Touch-target area is a separate decision and can extend beyond a compact visible control where neighboring controls allow it.
+
+## Map your decisions
+
+::: table
+
+- Recipe key: `control-roominess`
+  CSS property: `--ui-control-roominess`
+  What changes: Medium control height as a unitless multiple of the text base. Derives `--ui-control-size` and its small, medium, and large roles.
+
+- Recipe key: `scale-contrast`
+  CSS property: `--ui-scale-ratio`
+  What changes: The separation between sizes. At 1, the control sizes are equal; higher ratios separate them.
+
+- Recipe key: `rhythm`
+  CSS property: `--ui-rhythm`
+  What changes: Vertical Stack gaps and unitless line-height multipliers. Horizontal navigation and action-row gaps retain their own spacing.
+
+- Recipe key: `spacing`
+  CSS property: `--ui-spacing`
+  What changes: Gaps and padding independently of control heights and text ratios.
+
+- Recipe key: `space-curve`
+  CSS property: `--ui-space-curve`
+  What changes: How the spacing scale grows. 1 is linear; increasing toward 2 curves the intermediate steps while keeping stable endpoints.
+
+- Recipe key: `corner-roundness`
+  CSS property: `--ui-radius-md`
+  What changes: The shared corner family for controls and surfaces.
+
+- Recipe key: `line-weight`
+  CSS property: `--ui-border-width`
+  What changes: Shared border weight. Focus visibility has its own roles.
+
+:::
+
+## Keep height and space distinct
+
+If buttons and fields feel too tall, change **Control roominess**. If content feels crowded around otherwise well-proportioned controls, change **Spacing**. If stacked paragraphs and groups need more vertical breathing room, change **Rhythm**.
+
+```json
+{
+  "schemaVersion": 1,
+  "values": {
+    "text-size": "16px",
+    "control-roominess": "2.75",
+    "scale-contrast": "1.2",
+    "spacing": "1.1",
+    "rhythm": "1.1"
+  }
+}
+```
+
+In component markup, use supported props such as `size="sm"` on a control or `gap="l"` on Stack. Let the theme supply the shared values behind those choices.
+
+## Preserve units
+
+Base `text-size` is px-only and sets the document root. Other supported length inputs retain their CSS units, including rem, with generated guards for their documented bounds. Set the base on `:root`; a nested light/dark region shares that rem root.
+
+For older recipes, replace `density` with `spacing`. Replace a length-valued `control-size` with numeric `control-roominess` by dividing the desired medium height by the original text base. For example, `40px ÷ 16px` becomes `2.5`.
+
+[Back to Theme decisions](/theme-decisions/) · [Next: material and light](/theme-material/)
+
+</div>

package/docs/guides/05.(Theme reference)/04.theme-material.md

@@ -0,0 +1,90 @@
+---
+title: Material & light
+order: 4
+---
+
+<div data-looma-guide>
+
+# Material & light
+
+Choose whether surfaces feel flat, raised, matte, polished, or glassy. A shared light source gives their reflection and depth a consistent direction.
+
+## Give each decision a job
+
+::: table
+
+- Recipe key: `outer-depth`
+  CSS property: `--ui-outer-depth`
+  What changes: How strongly controls and floating surfaces rise above the page.
+
+- Recipe key: `inner-depth`
+  CSS property: `--ui-inner-depth`
+  What changes: Recession in fields and pressed controls.
+
+- Recipe key: `finish`
+  CSS property: `--ui-finish`
+  What changes: How strongly a surface catches a reflection, from matte to polished. Reflection also needs nonzero light strength.
+
+- Recipe key: `glassiness`
+  CSS property: `--ui-glassiness`
+  What changes: Frosting of the scene behind glass, primarily through decorative rims.
+
+- Recipe key: `surface-separation`
+  CSS property: `--ui-surface-separation`
+  What changes: The material offset around floating content, scaled by the popup's purpose and size.
+
+- Recipe key: `translucency`
+  CSS property: `--ui-overlay-translucency`
+  What changes: Transmission through decorative rims. At maximum, content plates also reveal a little of the scene.
+
+- Recipe key: `edge-light`
+  CSS property: `--ui-edge-light`
+  What changes: Light caught at the boundary, independently of depth.
+
+- Recipe key: `glow`
+  CSS property: `--ui-glow`
+  What changes: Reflected light beyond the surface, from a quiet halo to a stronger bloom.
+
+:::
+
+Depth changes elevation. Finish changes reflection. Transparency changes what shows through. You can change one while retaining the others: turning light strength to zero removes illumination while depth shadows remain.
+
+## Place the light
+
+::: table
+
+- Recipe key: `light-color`
+  CSS property: `--ui-light-color`
+  What changes: The reflected environment's color, independently of object pigment.
+
+- Recipe keys: `light-x`, `light-y`
+  CSS properties: `--ui-light-x`, `--ui-light-y`
+  What changes: Position relative to each surface. Coordinates run from 0 to 1; `0.5, 0` is top center.
+
+- Recipe key: `light-spread`
+  CSS property: `--ui-light-spread`
+  What changes: Concentrated illumination through a broader light source.
+
+- Recipe key: `light-strength`
+  CSS property: `--ui-light-strength`
+  What changes: Illumination intensity. Components and materials determine how they respond.
+
+:::
+
+In **Customize → Material & light**, drag the light source, use its arrow keys, or enter exact percentages. Shift moves faster; Home returns it to top center. Escape cancels a drag and restores its start.
+
+## Let components choose the treatment
+
+```html
+<ui-card variant="elevated">A standard raised card</ui-card>
+<ui-card variant="elevated" treatment="expressive">A raised card with the theme's material</ui-card>
+<ui-card treatment="expressive">Material treatment on an outlined card</ui-card>
+```
+
+`variant` chooses surface structure. `treatment` chooses how much decorative material it expresses. A matte theme stays matte even when a component requests expressive treatment. A card's tone changes its color while preserving its geometry.
+
+The content plane stays nearly opaque so text remains readable. Reduced-transparency and forced-colors preferences suppress ornamental reflection and glow; reduced transparency also disables backdrop blur.
+
+[Back to Theme decisions](/theme-decisions/) · [Next: motion](/theme-motion/)
+
+</div>

package/docs/guides/05.(Theme reference)/05.theme-motion.md

@@ -0,0 +1,57 @@
+---
+title: Motion
+order: 5
+---
+
+<div data-looma-guide>
+
+# Motion
+
+Set the pace and character of feedback once. Components use the shared duration and curve to make presses, openings, and other changes feel related.
+
+## Map your decisions
+
+::: table
+
+- Recipe key: `response-time`
+  CSS property: `--ui-motion-fast`
+  What changes: The shared feedback duration. Other durations derive from it; the base transition duration is 1.5 times this value.
+
+- Recipe key: `response-curve`
+  CSS property: `--ui-motion-ease`
+  What changes: How movement accelerates and settles.
+
+:::
+
+```json
+{
+  "schemaVersion": 1,
+  "values": {
+    "response-time": "150ms",
+    "response-curve": "cubic-bezier(0.2,0,0.2,1)"
+  }
+}
+```
+
+The CSS keeps the duration and curve as separate properties:
+
+```css
+:root {
+  --ui-motion-fast: 150ms;
+  --ui-motion-ease: cubic-bezier(0.2,0,0.2,1);
+}
+```
+
+## Compare the movement
+
+Open **Motion** in Customize. Replay the study, then open the real popover beside it. The study uses the shared curve and travels at three times the feedback duration, giving you time to see its acceleration.
+
+Curve handles support dragging and arrow keys, with numeric coordinates for precision. Escape or pointer cancellation restores the gesture start. Time values retain `ms` or `s`; number controls also accept arithmetic such as `150ms * 2`.
+
+## Respect reduced motion
+
+The exported theme includes reduced-motion rules that set shared durations to zero and neutralize the press scale. The customizer's study also respects the user's preference. When you author a component, use the shared motion roles and honor reduced motion in any additional behavior.
+
+[Back to Theme decisions](/theme-decisions/) · [Publish your system](/publish-your-system/)
+
+</div>

package/docs/index.d.ts

@@ -0,0 +1,59 @@
+export interface DocumentationGroup { id: string; label: string }
+export interface ExampleCode { language: string; code: string }
+export interface DocumentationExample {
+  id: string; name: string; title: string; description: string; markup: string;
+  resizable: boolean; stretch?: boolean; frameworks: Record<string, ExampleCode>; behavior?: string; bindings?: string;
+}
+export interface DocumentationComponent {
+  id: string; package: string; tag: string; title: string; description: string; group: string;
+  root: string; angularHost?: string; resource: string; source?: string; importSource?: string; navigationParent?: string;
+  targets: string[]; examples: DocumentationExample[];
+  attributes: Record<string, unknown>[]; properties: Record<string, unknown>[];
+  events: Record<string, unknown>[]; slots: Record<string, unknown>[];
+  designTokens: { sources?: string[]; component: Record<string, unknown>[]; shared: Record<string, unknown>[] };
+}
+export interface DocumentationCatalog {
+  schemaVersion: 1; package?: string; version?: string; groups: DocumentationGroup[];
+  resources?: { tag: string; package: string; resource: string }[]; components: DocumentationComponent[];
+}
+export interface DiscoveryRoot { directory: string; packageName: string; groups?: DocumentationGroup[] }
+export interface ThemeRecipe { schemaVersion: 1; values: Record<string, string>; origin?: string; fonts?: Partial<Record<'body-font' | 'display-font', string>>; presets?: Partial<Record<'material' | 'palette', string>> }
+export interface ThemeField { family: string; id: string; label: string; property: string | null; type: string; defaultValue: string; description: string; min?: number; max?: number; choices?: Record<string, string> }
+export interface DocumentationConfiguration {
+  title?: string; base?: string; origin?: string; outDir?: string; content?: string;
+  logo?: string | { light: string; dark?: string }; nav?: { label: string; href: string; position?: 'start' }[];
+  components?: DiscoveryRoot[]; catalogs?: string[]; categories?: Record<string, string>;
+  theme?: { recipe?: string; css?: string }; overrides?: string[];
+  recipe?: ThemeRecipe;
+}
+export interface DocumentationInput { root?: string; config?: DocumentationConfiguration; catalog?: DocumentationCatalog }
+export interface DocumentationSite {
+  root: string; config: DocumentationConfiguration; base: string; catalog: DocumentationCatalog;
+  examples: (DocumentationExample & { file: string; component: string; path: string })[];
+  generated: string; content: string; previews: string; redirects: Record<string, string>;
+}
+export interface DocumentationBuild { outDir: string; routes: readonly string[]; browserInputs: readonly string[]; site: DocumentationSite }
+export interface DocumentationServer { url: string; close(): Promise<void> }
+export function readCatalog(specifier?: string | URL): Promise<DocumentationCatalog>;
+export function discoverComponents(input: DiscoveryRoot & { root: string }): Promise<DocumentationCatalog>;
+export function mergeCatalogs(catalogs: DocumentationCatalog[], options?: { categories?: Record<string, string> }): DocumentationCatalog;
+export function prepareDocumentation(input: DocumentationInput & { root: string }): Promise<DocumentationSite>;
+export function buildDocumentation(input?: DocumentationInput): Promise<DocumentationBuild>;
+/** Optional MarkupKit integration; server tooling peers are loaded only when invoked. */
+export function documentationOptions(site: DocumentationSite): Promise<import('@threadlabs/markupkit').ApplicationOptions>;
+export function documentationPlugin(site: DocumentationSite): import('@threadlabs/markupkit').MarkupKitPlugin;
+export function initializeDocumentation(input?: { root?: string; title?: string }): Promise<{ config: DocumentationConfiguration; files: string[]; applicationImport: string }>;
+export function readConfiguration(root?: string): Promise<{ root: string; config: DocumentationConfiguration }>;
+export function buildProjectDocumentation(input?: DocumentationInput): Promise<DocumentationBuild>;
+export function devProjectDocumentation(input?: DocumentationInput & { port?: number; onError?: (error: unknown) => void }): Promise<DocumentationServer>;
+export function previewProjectDocumentation(input?: DocumentationInput & { port?: number }): Promise<DocumentationServer>;
+export const themeFields: readonly ThemeField[];
+export const startingPoints: Record<string, ThemeRecipe>;
+export function defaultRecipe(): ThemeRecipe;
+export const materialPresets: Record<string, { label: string; values: Record<string, string> }>;
+export function applyRefinement(input: ThemeRecipe, family: 'material' | 'palette', id: string): ThemeRecipe;
+export function refinementState(input: ThemeRecipe, family: 'material' | 'palette'): { id: string; customized: boolean };
+export function validateRecipe(input: unknown): ThemeRecipe;
+export interface ResolvedTheme { tokens: Record<string, string>; adjustments: { id: string; requested: string; resolved: string; reason: string }[] }
+export function deriveTheme(input: ThemeRecipe, options?: { mode?: 'light' | 'dark' }): ResolvedTheme;
+export function themeCSS(input: ThemeRecipe, systemCSS?: string, options?: { scope?: 'portable' | 'documentation' }): string;

package/docs/index.mjs

@@ -0,0 +1,4 @@
+export { readCatalog, discoverComponents, mergeCatalogs } from './catalog.mjs';
+export { prepareDocumentation, documentationOptions, documentationPlugin, buildDocumentation } from './site.mjs';
+export { defaultRecipe, startingPoints, themeFields, validateRecipe, deriveTheme, themeCSS, materialPresets, statusPresets, applyRefinement, refinementState } from './theme.mjs';
+export { initializeDocumentation, buildProjectDocumentation, devProjectDocumentation, previewProjectDocumentation, readConfiguration } from './commands.mjs';