# knadh/oat architecture

> Architecture diagram of the GitHub repository knadh/oat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/knadh/oat
- Repository: https://github.com/knadh/oat

## Overview

This repo is a **static, dependency-free UI component library** (“Oat UI”) consisting of:
- **Ship-ready CSS + minimal JS** for semantic HTML components (no framework).
- A **documentation / demo website** under `docs/`, likely built with a static site generator (the presence of `config.toml` + `templates/` strongly suggests Zola or similar).
- A **CI workflow** to publish the docs site (`.github/workflows/publish-website.yml`).

##### File-structure analysis (what components exist)
Top-level breakdown:
- `src/css/*` — the core library styles, organized by component (accordion, tooltip, tabs, etc.) + base/theme/utilities.
- `src/js/*` — minimal JS/WebComponent-like behavior for interactive components (dropdown, tabs, toast, tooltip, sidebar) + `base.js`.
- `docs/` — documentation website:
- `docs/config.toml` — site configuration (static generator config).
- `docs/content/**` — markdown pages (usage, customizing, and a page per component).
- `docs/templates/**` — HTML templates, component page templates, shortcodes (notably `shortcodes/demo.html` for embedding examples).
- `docs/static/**` — static assets for the site, including `main.js` and `CNAME` (custom domain for GitHub Pages).
- `.github/workflows/publish-website.yml` — publish automation for docs.
- `package.json` — likely used for lightweight tooling (minification, bundling, copying assets, etc.), even though the library itself is “zero dependencies” at runtime.
- `Makefile` — common in repos like this for build/publish shortcuts (e.g., build docs, copy assets, release).

##### README cues (how it behaves at runtime)
Key behavioral constraints to reflect:
- **“Just include tiny CSS and JS files”**: runtime architecture is simply:
- Browser loads Oat CSS
- Browser loads Oat JS (optional, only for interactive components)
- Semantic HTML attributes/tags get styled contextually; minimal DOM scripting for dynamic widgets
- **No framework / no runtime deps**: highlight *absence* of backend/services.
- **Docs site** is the “product surface” for discovering components.

##### Oat UI Library (Source)
- `src/css/00-base.css`
- `src/css/01-theme.css`
- `src/css/utilities.css`
- `src/css/<component>.css` (accordion, button, card, etc.)
- `src/js/base.js`
- `src/js/<component>.js` (dropdown, tabs, toast, tooltip, sidebar)

##### Distributable Assets (what users actually include)
- “oat.css” (or equivalent compiled/combined CSS output)
- “oat.js” (or equivalent minimal JS output)
Even if the exact filenames aren’t in the tree, represent the concept as “Built CSS/JS artifacts”.

##### Documentation Website
- Content: `docs/content/*` (markdown pages)
- Templates: `docs/templates/*` (layout, component page templates)
- Shortcodes: `docs/templates/shortcodes/demo.html` (example embedding)
- Static: `docs/static/*` (CNAME, `main.js`, other static files)

##### CI/CD Publishing
- GitHub Actions: `.github/workflows/publish-website.yml`
- Target: GitHub Pages / static hosting (plus `docs/static/CNAME` for domain)

##### Consumer Applications (external)
- “Any HTML page / web app” that includes the CSS/JS.
- Browser runtime.

##### `src/js/*` → (Build/packaging step) → “oat.js”
3) `docs/content/*.md` + `docs/templates/*.html` + `docs/config.toml` → (Static site generator build) → “Static site output (HTML/CSS/JS)”
##### End user browser
- Loads docs site pages (HTML) → references Oat CSS/JS for examples/demos
- Loads consumer app HTML → includes Oat CSS/JS → DOM behavior for dropdown/tabs/toast/etc.

A small runtime interaction cluster:
- “Browser DOM” ↔ “Oat JS modules” (event listeners, attribute-based behavior)
- “Semantic HTML / attributes” → “Oat CSS” (contextual styling)

##### Important architectural patterns to highlight
- **“CSS-first, semantic styling”**: styling based on elements/attributes rather than class-heavy markup.
- **Component-per-file organization**: each component has its own CSS file; interactive components have their own JS file.
- **Docs-as-a-product**: component documentation is a first-class subsystem.
- **No backend**: everything is static; hosting is static; behavior is purely client-side.

##### Technologies to explicitly label
- “Plain HTML + CSS”
- “Vanilla JS (minimal; some components as WebComponents / custom elements conceptually)”
- “Static site generator (from `config.toml` + templates/content structure)”
- “GitHub Actions” → “GitHub Pages” (+ custom domain via CNAME)

##### Split into two consumers
- **Docs site build** (`docs/*` → generator) → **GitHub Pages**
- **External consumer app** (any HTML) → **Browser runtime**

##### “Don’t overthink it” but be maximally decomposed
Because this project is simple, being “very detailed” means:
- Representing **each component category** (e.g., “Interactive JS components: dropdown/tabs/toast/tooltip/sidebar” vs “CSS-only components: badge/card/grid/typography/etc.”)
- Showing the **docs authoring flow** (markdown + templates + shortcodes)
- Showing **publishing** separately from **building**

**CSS components (`src/css/`)**
- Base/Theme/Utilities: `00-base.css`, `01-theme.css`, `utilities.css`, `animations.css`
- Components: accordion, alert, badge, button, card, dialog, dropdown, form, grid, meter?, progress, sidebar, skeleton, spinner, switch?, table, tabs, toast, tooltip, typography

**JS components (`src/js/`)**
- Core: `base.js`
- Interactive: `dropdown.js`, `sidebar.js`, `tabs.js`, `toast.js`, `tooltip.js`

**Docs pages (`docs/content/components/`)**
- One page per component (accordion…typography) + `usage.md`, `customizing.md`, `other-libs.md`

**Docs templating**
- `docs/templates/base.html`, `index.html`, component templates, `shortcodes/demo.html`

**Publish**
- `.github/workflows/publish-website.yml` → GitHub Pages + `docs/static/CNAME`

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Zones: Source -> Build -> Outputs -> Runtime/Hosting
  %% =========================

  subgraph "Authoring (Repo Source)"
    direction TB

    subgraph "Oat UI Library Source"
      direction TB

      CSSDir["CSS Source (component-per-file)"]:::source
      subgraph "src/css/*"
        direction TB
        CSSBase["Base/Theme/Utilities\n00-base.css\n01-theme.css\nutilities.css\nanimations.css"]:::source
        CSSComponents["Component CSS\naccordion/alert/badge/button/card/dialog/dropdown/form/grid/progress/sidebar/skeleton/spinner/table/tabs/toast/tooltip"]:::source
      end

      JSDir["JS Source (minimal, vanilla)"]:::source
      subgraph "src/js/*"
        direction TB
        JSBase["Core runtime\nbase.js"]:::source
        JSComponents["Interactive modules\ndropdown/sidebar/tabs/toast/tooltip"]:::source
      end
    end

    subgraph "Documentation Site Source (Static Site Generator Inputs)"
      direction TB
      DocsConfig["Site config\nconfig.toml"]:::source

      DocsContent["Content (Markdown)\nUsage/Customizing/Other-libs\n+ component pages"]:::source
      DocsContentComponents["Component docs pages\n(one per component)"]:::source

      DocsTemplates["Templates (HTML)\nbase/index/page"]:::source
      DocsComponentTemplates["Component templates\ncomponents/page + section"]:::source
      DocsShortcodes["Shortcodes\ndemo embedding"]:::source

      DocsStatic["Static assets\nmain.js + CNAME"]:::source
    end
  end

  subgraph "Build / Tooling"
    direction TB
    Tooling["Build/Packaging tooling\n(Makefile + package.json scripts)"]:::build
    LibBuild["Bundle/minify/copy\nLibrary assets"]:::build
    SiteBuild["Static site generator build\n(render templates + markdown)"]:::build
  end

  subgraph "Artifacts (Outputs)"
    direction TB
    OatCSS["Built CSS artifact\n(oat.css)"]:::artifact
    OatJS["Built JS artifact\n(oat.js)"]:::artifact
    SiteOut["Generated static site\nHTML/CSS/JS"]:::artifact
  end

  subgraph "Publishing (CI/CD)"
    direction TB
    GHA["GitHub Actions workflow\npublish-website.yml"]:::ci
    Pages["GitHub Pages (Static Hosting)\nCustom domain via CNAME"]:::hosting
  end

  subgraph "Runtime (No Backend)"
    direction TB

    subgraph "Docs Site Runtime"
      direction TB
      DocsBrowser["Browser loads docs pages"]:::runtime
      DocsHTML["Docs HTML pages\n(demos + examples)"]:::artifact
      DemoMarkup["Semantic HTML + attributes\n(example markup)"]:::runtime
    end

    subgraph "External Consumer Runtime"
      direction TB
      ConsumerApp["Any HTML page / web app\n(includes Oat assets)"]:::external
      ConsumerBrowser["Browser (DOM + events)"]:::runtime
      ConsumerMarkup["Semantic HTML + attributes\n(app markup)"]:::runtime
    end

    subgraph "Client-side behavior"
      direction TB
      CSSStyling["CSS-first styling\n(contextual/semantic)"]:::runtime
      JSBehavior["Vanilla JS behaviors\n(event listeners, toggles state)"]:::runtime
    end
  end

  %% =========================
  %% Relationships
  %% =========================

  %% Library build
  CSSDir -->|"authored_as"| CSSBase
  CSSDir -->|"authored_as"| CSSComponents
  JSDir -->|"authored_as"| JSBase
  JSDir -->|"authored_as"| JSComponents

  CSSBase -->|"bundles/minifies"| LibBuild
  CSSComponents -->|"bundles/minifies"| LibBuild
  JSBase -->|"bundles/minifies"| LibBuild
  JSComponents -->|"bundles/minifies"| LibBuild
  Tooling -->|"runs"| LibBuild

  LibBuild -->|"outputs"| OatCSS
  LibBuild -->|"outputs"| OatJS

  %% Docs build
  DocsConfig -->|"configures"| SiteBuild
  DocsContent -->|"renders"| SiteBuild
  DocsContentComponents -->|"renders"| SiteBuild
  DocsTemplates -->|"applies_layout"| SiteBuild
  DocsComponentTemplates -->|"component_layout"| SiteBuild
  DocsShortcodes -->|"embeds_demos"| SiteBuild
  DocsStatic -->|"copied_as_static"| SiteBuild
  Tooling -->|"invokes"| SiteBuild

  %% Docs output includes library artifacts for demos
  OatCSS -->|"included_via_<link>"| SiteBuild
  OatJS -->|"included_via_<script>"| SiteBuild
  SiteBuild -->|"generates"| SiteOut

  %% Publish
  SiteOut -->|"published_by"| GHA
  GHA -->|"deploys_to"| Pages

  %% Runtime: docs
  Pages -->|"serves"| DocsBrowser
  SiteOut -->|"served_as"| DocsHTML
  DocsBrowser -->|"renders"| DocsHTML
  DocsHTML -->|"contains"| DemoMarkup
  DocsBrowser -->|"loads"| OatCSS
  DocsBrowser -->|"loads_optional"| OatJS

  DemoMarkup -->|"styled_by"| CSSStyling
  OatCSS -->|"applies_styles"| CSSStyling
  OatJS -->|"attaches_listeners"| JSBehavior
  DocsBrowser -->|"triggers_events"| JSBehavior
  JSBehavior -->|"updates_DOM_state"| DocsBrowser

  %% Runtime: consumers
  ConsumerApp -->|"includes_via_<link>/<script>"| OatCSS
  ConsumerApp -->|"includes_via_<link>/<script>"| OatJS
  ConsumerApp -->|"opened_in"| ConsumerBrowser
  ConsumerBrowser -->|"renders"| ConsumerMarkup
  ConsumerMarkup -->|"styled_by"| CSSStyling
  ConsumerBrowser -->|"executes"| JSBehavior

  %% =========================
  %% Click events (from component_mapping)
  %% =========================
  click CSSDir "https://github.com/knadh/oat/tree/master/src/css/"
  click CSSBase "https://github.com/knadh/oat/blob/master/src/css/00-base.css"
  click CSSBase "https://github.com/knadh/oat/blob/master/src/css/01-theme.css"
  click CSSBase "https://github.com/knadh/oat/blob/master/src/css/utilities.css"
  click CSSBase "https://github.com/knadh/oat/blob/master/src/css/animations.css"

  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/accordion.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/alert.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/badge.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/button.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/card.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/dialog.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/dropdown.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/form.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/grid.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/progress.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/sidebar.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/skeleton.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/spinner.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/table.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/tabs.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/toast.css"
  click CSSComponents "https://github.com/knadh/oat/blob/master/src/css/tooltip.css"

  click JSDir "https://github.com/knadh/oat/tree/master/src/js/"
  click JSBase "https://github.com/knadh/oat/blob/master/src/js/base.js"
  click JSComponents "https://github.com/knadh/oat/blob/master/src/js/dropdown.js"
  click JSComponents "https://github.com/knadh/oat/blob/master/src/js/sidebar.js"
  click JSComponents "https://github.com/knadh/oat/blob/master/src/js/tabs.js"
  click JSComponents "https://github.com/knadh/oat/blob/master/src/js/toast.js"
  click JSComponents "https://github.com/knadh/oat/blob/master/src/js/tooltip.js"

  click DocsConfig "https://github.com/knadh/oat/blob/master/docs/config.toml"
  click DocsContent "https://github.com/knadh/oat/tree/master/docs/content/"
  click DocsContentComponents "https://github.com/knadh/oat/tree/master/docs/content/components/"
  click DocsTemplates "https://github.com/knadh/oat/blob/master/docs/templates/base.html"
  click DocsTemplates "https://github.com/knadh/oat/blob/master/docs/templates/index.html"
  click DocsTemplates "https://github.com/knadh/oat/blob/master/docs/templates/page.html"
  click DocsComponentTemplates "https://github.com/knadh/oat/blob/master/docs/templates/components/page.html"
  click DocsComponentTemplates "https://github.com/knadh/oat/blob/master/docs/templates/components/section.html"
  click DocsShortcodes "https://github.com/knadh/oat/blob/master/docs/templates/shortcodes/demo.html"
  click DocsStatic "https://github.com/knadh/oat/blob/master/docs/static/main.js"
  click DocsStatic "https://github.com/knadh/oat/tree/master/docs/static/CNAME"

  click GHA "https://github.com/knadh/oat/blob/master/.github/workflows/publish-website.yml"
  click Tooling "https://github.com/knadh/oat/blob/master/package.json"
  click Tooling "https://github.com/knadh/oat/tree/master/Makefile"

  %% =========================
  %% Styles
  %% =========================
  classDef source fill:#E8F0FF,stroke:#2B5FDB,stroke-width:1.5px,color:#0B1F52
  classDef build fill:#FFF3D6,stroke:#B26A00,stroke-width:1.5px,color:#4A2A00
  classDef artifact fill:#EAF8EE,stroke:#1E7D3A,stroke-width:1.5px,color:#0F3B1B
  classDef ci fill:#F3E8FF,stroke:#6D28D9,stroke-width:1.5px,color:#2E1065
  classDef hosting fill:#E6FFFA,stroke:#0F766E,stroke-width:1.5px,color:#083344
  classDef runtime fill:#F1F5F9,stroke:#334155,stroke-width:1.5px,color:#0F172A
  classDef external fill:#FFE4E6,stroke:#BE123C,stroke-width:1.5px,color:#4C0519
```
