docs(readme): promote framework adapters, trim theming, fix structure#247
Merged
Conversation
Restructures the root README so first-time visitors see install →
working example → framework options → catalogue without scrolling past
project narrative.
Changes:
- New "Framework adapters" section between Installation and Components
with a comparison table for all five published adapters (React, Vue,
Angular, Svelte, Solid) linking to each adapter's README + npm page.
Previously the README mentioned React and Angular only.
- Theming section trimmed from 37 lines to 6: one paragraph, the eight
preset names, and links to docs/x-theme.md (full API) and
docs/THEMING.md (token catalogue). registerPreset and CSS-override
examples are already in docs/x-theme.md.
- Installation gains a working "Quick start" snippet — minimal HTML
page rendering x-button + x-alert inside x-theme — replacing the
bare import-init stub.
- Origin story ("Why BareDOM?") moved to the bottom as "About" so it
no longer pushes install/quick-start below the fold.
- BareForge section moved below Components — companion product reads
as "also check this out" rather than competing with the catalogue.
- "Why web components?" heading fixed from H1 to H2 (was a hierarchy
bug breaking the section nesting).
- Custom Elements Manifest promoted from a parenthetical inside the
TypeScript bullet to its own bullet — it's what makes the typed
adapters work and was previously buried.
Net: 290 lines (was 300), 62 insertions / 72 deletions.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ve catalogue
Three follow-up edits on top of the original restructure:
1. Merged "Why web components?" and "Design Principles" into a single
"Why BareDOM?" section. The two sections overlapped on accessibility,
theming, and mobile (same content, different framing); the unique
value from Design Principles (stateless rendering, zero runtime) is
folded into the merged 7-bullet list. Net: 15 bullets across two
sections → 7 bullets in one.
2. Added a dedicated "Time-Travel Debugger" section between Components
and Theming. x-trace-history was previously a one-line mention buried
inside the Stateless bullet; it's a flagship dev tool (records every
CustomEvent dispatch, attribute change, instance-field write, and
lifecycle callback; cause→effect navigation; URL-based bug-sharing;
zero production cost when inactive). Stateless bullet now contains
only a forward reference.
3. Moved the full per-component catalogue to docs/components.md and
replaced the README section with a compact overview table.
- The original README listed 58 components across 6 categories. The
library actually has 105 exports (103 UI components + x-theme +
x-trace-history). All 45 missing were entirely absent from the
README, including the kinetics/organic/effects/scroll clusters that
differentiate BareDOM from generic component libraries.
- docs/components.md now catalogues all 103 components across 11
categories (Form 23, Feedback 11, Navigation 8, Layout 10, Data 11,
Overlay 9, Display 6, Animation 6, Effects 12, Scroll 5, Utility 2).
- README overview is an 11-row category table with counts + example
names, linking to docs/components.md for the full table.
README: 211 lines (was 290 in the first restructure commit, 300 before
this PR series began).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…components When adding a new component, two cross-cutting docs need updating that neither tests nor lint catch: - docs/components.md (the full per-component catalogue): a row in the appropriate category table, with taxonomy guidance to flag gaps before inventing new categories. - README.md (the Components overview): bump the count in the category row, plus the Examples column for flagship components. The 45-component gap fixed in this PR is concrete evidence the omission has happened repeatedly. Adding the rule to the existing registration checklist (Stage 3 of "Development Pipeline for New Components") keeps it next to the other single-source-of-truth checklist items (shadow-cljs.edn, package.json, registry.cljs, public/index.html). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructures the root README so first-time visitors hit install → working example → framework options → catalogue → debugger → theming without scrolling past project narrative or stale content. The five published adapters were previously invisible; the value-prop and design-principles sections duplicated each other; the catalogue listed only 58 of 105 components; and the x-trace-history time-travel debugger was a one-line mention buried inside a bullet.
This PR contains two commits:
Commit 1 — original restructure
registerPresetand CSS-override examples already live indocs/x-theme.md.<x-button>+<x-alert>inside<x-theme>.# Why web components?→## Why web components?— H1/H2 hierarchy bug fixed.Commit 2 — value-prop merge + Time-Travel Debugger + catalogue split
x-trace-historywas a one-line mention buried inside the Stateless bullet; it's a flagship dev tool (records every CustomEvent dispatch, attribute change, instance-field write, and lifecycle callback; cause→effect timeline; URL-based bug-sharing; zero production cost when inactive).docs/components.md, README gets a compact overview. The original README listed 58 of 105 components; all 45 missing were entirely absent, including the kinetics/organic/effects/scroll clusters that differentiate BareDOM from generic component libraries. The newdocs/components.mdcatalogues all 103 UI components across 11 categories (Form 23, Feedback 11, Navigation 8, Layout 10, Data 11, Overlay 9, Display 6, Animation 6, Effects 12, Scroll 5, Utility 2).Final README structure
What is BareDOM → Why BareDOM → Installation + Quick start → Framework adapters → Components (overview) → Time-Travel Debugger → Theming → BareForge → Bundle Size → Browser Support → Development → About → License
211 lines (was 300 before this PR series began).
Test plan
./docs/*.mdand./adapters/*/README.mdlinks resolvedevelopment.md#debug-mode,installation.md#clojurescript-via-clojars,installation.md#vanilla-htmljs-via-es-modules)docs/components.mdexists and lists all 103 UI componentsx-theme+x-trace-history= 105 exports, matchingpackage.json## Why web components?H1→H2 fix lands🤖 Generated with Claude Code