How knadh/oat works
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