component.json versioning

assets/docs/getting-started/changelog.md

@@ -8,11 +8,24 @@ order: 5
 
 Latest updates and announcements.
 
+# August 2026 - Component Versioning & components.json
+
+As Buridan UI's component library has grown, we've run into a familiar problem: components change over time, and sometimes those changes aren't backward compatible. Until now, updating a component in the registry meant every project pulling that component got the new version, whether it was ready for it or not. This update fixes that.
+
+Components can now publish multiple versions side by side, and the CLI lets you choose exactly which one you want.
+
+- **Version pinning:** Install a specific version of any component with `buridan add button@1.0.0`, or leave off the version to get the latest one automatically. Your project stays exactly as you set it up, even as new versions get published to the registry.
+- **Smart dependency resolution:** If a component you're adding depends on another versioned component, the CLI resolves it sensibly. An explicit version you pin always takes priority over whatever a dependency would otherwise pull in, so you're never surprised by a version swap you didn't ask for.
+- **A new components.json manifest:** Every `buridan add` and `buridan apply` now records what's actually installed in your project, including each component's version and your currently applied theme preset. It's a simple, readable log of your project's setup, not something you need to edit by hand, but useful to have around when you're checking what's installed or diffing changes over time.
+- **Clear conflict handling:** If two different versions of the same component end up requested at once, the CLI warns you about it instead of quietly picking one and leaving you to find out later.
+
+None of this changes how components look or behave today. It just means your project can move at its own pace as the registry evolves underneath it.
+
 # July 2026 - Native/Buridan
 
 Under-the-hood layouts can get incredibly messy when they are wrapped in too many heavy React abstractions. In this update, we went back to the drawing board and completely rewrote Buridan's core elements to rely purely on native HTML elements (`rx.el.*`) instead of wrapping everything in heavy, custom third-party components.
 
-By ditching complex client-side libraries like Radix UI and Base UI, we've stripped away massive JavaScript bundles and unnecessary DOM nodes. 
+By ditching complex client-side libraries like Radix UI and Base UI, we've stripped away massive JavaScript bundles and unnecessary DOM nodes.
 
 We did this for a couple of really practical reasons that make a huge difference in day-to-day development:
 
@@ -21,4 +34,4 @@ We did this for a couple of really practical reasons that make a huge difference
 - **Featherlight DOM Overhead:** Stripping out nested wrapper divs means the browser has fewer nodes to paint. Your rendered page markup is incredibly clean, which makes styling adjustments with Tailwind CSS utilities extremely predictable—no more fighting arbitrary class specificity clashes.
 - **Predictable 1:1 API mapping:** Native tags are standard. There are no hidden proprietary parameters, undocumented properties, or unexpected behavioral overrides. What you write in your Python code maps 1:1 with what the browser actually renders in the DOM tree.
 
-It’s a simpler, much more robust foundation that keeps your apps lightweight, super-fast, and incredibly responsive.
+It's a simpler, much more robust foundation that keeps your apps lightweight, super-fast, and incredibly responsive.

assets/docs/getting-started/cli.md

@@ -34,7 +34,7 @@ buridan init
 
 # apply
 
-Apply a theme preset to your project. Generates `:root` and `.dark` CSS variable blocks in `assets/globals.css` based on the preset ID from the theme builder.
+Apply a theme preset to your project. Generates `:root` and `.dark` CSS variable blocks in `assets/globals.css` based on the preset ID from the theme builder, and records the applied theme in [`components.json`](/docs/components-json).
 
 ```bash
 buridan apply --preset <ID>
@@ -51,6 +51,8 @@ buridan apply --preset b0
 buridan apply --preset b2D0wqNxT
 ```
 
+Re-running `buridan apply` with a different preset overwrites the theme section of `components.json` and the generated CSS variables — it does not touch any components you've already added.
+
 # add
 
 Add components and their dependencies to your project.
@@ -71,13 +73,42 @@ Blocks (charts, dashboards, etc.) can be added the same way:
 buridan add line_chart_01
 ```
 
-Components are placed in `components/`, blocks in `blocks/`. Dependencies are resolved and added automatically.
+Components are placed in `components/`, blocks in `blocks/`. Dependencies are resolved and added automatically. Every install updates the `components` section of [`components.json`](/docs/components-json) with the name and version of each installed component.
 
 > **Note:** Components require a theme to render correctly. Run `buridan apply` before using components.
 
+## Versioning
+
+Some components have more than one published version. By default, `add` installs the latest available version:
+
+```bash
+buridan add button
+```
+
+To pin a specific version, append `@<version>` to the component name:
+
+```bash
+buridan add button@1.0.0
+```
+
+Version pins you specify explicitly always take priority over versions pulled in automatically by another component's dependencies. For example, if you run:
+
+```bash
+buridan add card button@1.0.0
+```
+
+and `card` normally depends on the latest `button`, your explicit `button@1.0.0` pin wins — `card` will be installed against `button@1.0.0`, not whatever the latest version happens to be.
+
+If you pin the same component to two different versions in one command (or the CLI otherwise detects a genuine conflict it can't resolve), it prints a warning and keeps the first version it resolved:
+
+```bash
+buridan add button@1.0.0 button@2.0.0
+# Warning: 'button' requested at both 1.0.0 and 2.0.0; keeping 1.0.0.
+```
+
 # list
 
-Display all available components and blocks.
+Display all available components and blocks. If a component has multiple published versions, each version is listed separately (e.g. `button@1.0.0`, `button@2.0.0`).
 
 ```bash
 buridan list

assets/docs/getting-started/components-json.md

@@ -0,0 +1,111 @@
+---
+title: "components.json"
+description: "Configuration and state tracked automatically for your project."
+order: 4
+---
+
+# components.json
+
+The `components.json` file tracks the components and theme currently installed in your project.
+
+Unlike some other CLI tools, you don't create or edit this file by hand, the `buridan` CLI creates and updates it automatically the first time you run `buridan apply` or `buridan add`. Its main purpose is to give you (and the CLI) a single place to see exactly what's installed, at what version, and under what theme.
+
+**Note:** `components.json` is written to the root of your Reflex project, alongside `rxconfig.py`. It's safe to commit to version control, treat it like a lockfile for your design system.
+
+# Structure
+
+```json
+{
+  "components": {
+    "button": "1.0.0",
+    "card": "latest",
+    "core": "latest"
+  },
+  "theme": {
+    "preset": "b0",
+    "baseId": "neutral",
+    "colorId": "blue",
+    "chartId": "blue",
+    "styleId": "default",
+    "fontId": "inter",
+    "radius": "0.5rem"
+  }
+}
+```
+
+The two sections are updated independently, running `buridan add` never touches `theme`, and running `buridan apply` never touches `components`.
+
+# components
+
+A map of installed component names to the version installed.
+
+```json
+{
+  "components": {
+    "button": "1.0.0"
+  }
+}
+```
+
+- The key is the component's registry name, without any `@version` suffix.
+- The value is either a specific version string (e.g. `"1.0.0"`) if you pinned one with `buridan add button@1.0.0`, or the literal string `"latest"` if you installed it unpinned, or if the component doesn't have multiple published versions.
+
+This section is updated every time you run `buridan add`. See the [CLI docs](/docs/getting-started/cli#versioning) for how version pinning and conflicts are resolved.
+
+# theme
+
+Records the theme preset currently applied to your project.
+
+```json
+{
+  "theme": {
+    "preset": "b0",
+    "baseId": "neutral",
+    "colorId": "blue",
+    "chartId": "blue",
+    "styleId": "default",
+    "fontId": "inter",
+    "radius": "0.5rem"
+  }
+}
+```
+
+This section is written by `buridan apply --preset <ID>` and fully overwritten (not merged) on every subsequent `apply`, it always reflects only the most recently applied preset.
+
+### theme.preset
+
+The raw preset ID from the [theme builder](/docs/getting-started/cli#create), exactly as passed to `--preset`. This is the source of truth for the rest of the fields below, since it fully encodes the theme, it's the most reliable value to reference if you ever need to reconstruct or re-apply the same theme programmatically.
+
+```json
+{
+  "theme": {
+    "preset": "b2D0wqNxT"
+  }
+}
+```
+
+### theme.baseId
+
+The base theme (background, foreground, and neutral tones) the preset is built on.
+
+### theme.colorId
+
+The accent color palette applied on top of the base theme.
+
+### theme.chartId
+
+The color palette used for chart-specific CSS variables (`--chart-1` through `--chart-5`, etc.). This can differ from `colorId` if the preset uses a separate chart palette.
+
+### theme.styleId
+
+The component style variant (e.g. spacing, shadow, and border conventions) the preset applies.
+
+### theme.fontId
+
+The font family applied by the preset.
+
+### theme.radius
+
+The border-radius value applied by the preset, e.g. `"0.5rem"`. Omitted from `components.json` if the preset doesn't override the style's own default radius.
+
+Any field above that wasn't set by a given preset is left out of `components.json` entirely rather than written as `null`, so the file only ever shows what was actually specified.

assets/llms.txt

@@ -9,6 +9,7 @@
 - [CLI](https://native.buridan.dev/docs/getting-started/cli): CLI page.
 - [dev.py](https://native.buridan.dev/docs/getting-started/dev): dev.py page.
 - [JavaScript](https://native.buridan.dev/docs/getting-started/javascript): JavaScript page.
+- [components.json](https://native.buridan.dev/docs/getting-started/components-json): components.json page.
 - [Changelog](https://native.buridan.dev/docs/getting-started/changelog): Changelog page.
 
 ## Resources