Metadata-Version: 2.4
Name: cjm-fasthtml-design-system
Version: 0.0.2
Summary: Named UI role recipes (panels, chrome, insets) for FastHTML applications — a stable abstraction layer over DaisyUI and Tailwind primitives.
Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
License: Apache-2.0
Project-URL: Repository, https://github.com/cj-mills/cjm-fasthtml-design-system
Project-URL: Documentation, https://cj-mills.github.io/cjm-fasthtml-design-system/
Keywords: nbdev
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-fasthtml
Requires-Dist: cjm-fasthtml-app-core
Requires-Dist: cjm-fasthtml-tailwind
Requires-Dist: cjm-fasthtml-daisyui
Dynamic: license-file

# cjm-fasthtml-design-system


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Install

``` bash
pip install cjm_fasthtml_design_system
```

## Role in the Multi-Workflow Pipeline

This library sits between UI-bearing consumer libraries and the
underlying styling primitives:

    Consumers (page-centric libraries, host apps, demo apps)
        ↓ depend on
    Layout primitives (cjm-fasthtml-app-core: page chrome, column+queue, toolbar)
        ↓ depend on
    Design-system recipes (THIS LIBRARY: panels, chrome, insets, ...)
        ↓ depend on
    Styling primitives (cjm-fasthtml-daisyui, cjm-fasthtml-tailwind: tokens)

Consumers import *named roles* (`panels.dashboard_tile`,
`chrome.column_header`) instead of reaching for styling tokens directly.
This makes coordinated styling changes a single-file edit in this
library rather than N-file edits across every consumer, and keeps the
role API stable across a potential future FastHTML-to-native port.

## Design System Document

The authoritative specification of principles (P1–P12), conventions
(V1–V10…), interaction archetypes, layout primitives, component
primitives, gap catalog, and priority tasks lives in the
living-reference Markdown document at:

`claude-docs/design-system/multi-workflow-design-system.md`

(hosted in the decomposition workflow repo — the doc governs UI/UX
decisions across the entire multi-workflow pipeline and predates this
code-side codification.)

This library is the running-code companion to that document. Each
codified convention maps to a notebook in `nbs/`:

| Convention | Notebook | Module | What it codifies |
|:---|:---|:---|:---|
| V10 Panel variants | `nbs/panels.ipynb` | `cjm_fasthtml_design_system.panels` | P1–P4 full-panel recipes |
| V10 Chrome variants | `nbs/chrome.ipynb` | `cjm_fasthtml_design_system.chrome` | C1–C2 column header/footer recipes |
| V10 Inset variants | `nbs/insets.ipynb` | `cjm_fasthtml_design_system.insets` | I1 opacity-modulated inset recipes |

Future codifications (icon-size roles, button roles, destructive-confirm
composition, text-role tiers) will land as additional notebooks
following the same convention-to-notebook mapping.

## Usage

Every recipe module exports a module-level instance of a frozen
dataclass. Consumers import the instance and use attribute access:

``` python
from fasthtml.common import Div

from cjm_fasthtml_design_system.panels import panels
from cjm_fasthtml_design_system.chrome import chrome
from cjm_fasthtml_design_system.insets import insets

from cjm_fasthtml_tailwind.core.base import combine_classes
from cjm_fasthtml_tailwind.utilities.sizing import w
from cjm_fasthtml_tailwind.utilities.spacing import m

# Stand-alone use
Div(..., cls=panels.structural_container)

# Composable with site-specific modifiers
Div(..., cls=combine_classes(w.full, m.t(4), panels.content_panel))

# Chrome sits inside a panel
Div(
    Div('Header', cls=chrome.column_header),
    Div('Body'),
    Div('Status', cls=chrome.column_footer),
    cls=panels.structural_container,
)
```

**Why frozen dataclass:** renaming a field is a breaking change
*announced in the type*, which enforces namespace-as-public-contract
discipline. Consumers can’t accidentally mutate roles at runtime. A
native-platform port replaces the instantiation while keeping the class
shape stable; consumer imports never move.

**Why per-category modules:** panels, chrome, and insets will evolve at
different cadences. Keeping them separate means a change to one category
doesn’t force re-export of the others.

## Extending the Library

When a new convention emerges in the design-system document (e.g., G6
icon-size roles, V1 button-role codification, G8 destructive-confirm
composition), add a new notebook under `nbs/` following the V10 pattern:

1.  Create `nbs/<category>.ipynb` with `#| default_exp <category>`.
2.  Define a frozen `XVariants` dataclass enumerating the roles.
3.  Instantiate it at module scope as a singleton (e.g.,
    `x_variants = XVariants(...)`).
4.  Add attribute-level tests asserting each role contains its expected
    primitives.
5.  Update this index’s convention-to-notebook table.

The recipe layer’s public contract is the set of dataclass class names
and field names. Internal composition (which primitives each recipe
combines) can evolve without breaking consumers as long as the field
names stay stable.

## Project Structure

    nbs/
    ├── chrome.ipynb # Named chrome-role recipes for header and footer bands that accompany a content panel. Chrome uses directional borders (top or bottom) and intrinsic padding to signal its role as a structural band, with `border_radius.box` so it reads as a self-contained surface whether placed as a page-level sibling of a panel or nested inside one.
    ├── insets.ipynb # Named inset-role recipes for opacity-modulated low-emphasis regions *inside* a panel. Insets never stand alone — they're sub-regions that need visual grouping without adding a second panel border.
    └── panels.ipynb # Named panel-role recipes for full content containers with `border_radius.box`. Each role composes a specific set of DaisyUI and Tailwind primitives and exposes a stable attribute-access API for consumers.

Total: 3 notebooks

## Module Dependencies

``` mermaid
graph LR
    chrome[chrome<br/>Chrome Variants]
    insets[insets<br/>Inset Variants]
    panels[panels<br/>Panel Variants]
```

No cross-module dependencies detected.

## CLI Reference

No CLI commands found in this project.

## Module Overview

Detailed documentation for each module in the project:

### Chrome Variants (V10) (`chrome.ipynb`)

> Named chrome-role recipes for header and footer bands that accompany a
> content panel. Chrome uses directional borders (top or bottom) and
> intrinsic padding to signal its role as a structural band, with
> `border_radius.box` so it reads as a self-contained surface whether
> placed as a page-level sibling of a panel or nested inside one.

#### Import

``` python
from cjm_fasthtml_design_system.chrome import (
    chrome,
    ChromeVariants
)
```

#### Classes

``` python
class ChromeVariants:
    "Named chrome-role recipes (V10). Header/footer bands with directional borders, rounded corners."
```

### Inset Variants (V10) (`insets.ipynb`)

> Named inset-role recipes for opacity-modulated low-emphasis regions
> *inside* a panel. Insets never stand alone — they’re sub-regions that
> need visual grouping without adding a second panel border.

#### Import

``` python
from cjm_fasthtml_design_system.insets import (
    insets,
    InsetVariants
)
```

#### Classes

``` python
class InsetVariants:
    "Named inset-role recipes (V10). Opacity-modulated low-emphasis regions inside a panel."
```

### Panel Variants (V10) (`panels.ipynb`)

> Named panel-role recipes for full content containers with
> `border_radius.box`. Each role composes a specific set of DaisyUI and
> Tailwind primitives and exposes a stable attribute-access API for
> consumers.

#### Import

``` python
from cjm_fasthtml_design_system.panels import (
    panels,
    PanelVariants
)
```

#### Classes

``` python
class PanelVariants:
    "Named panel-role recipes (V10). Each field is a pre-composed CSS class string."
```
