Split the CSS output into separate bundles instead of one style.css
base.css (reset/typography), components.css, docs.css (this site's own
chrome), and patterns.css (Loop/Archive) are now built and linked
separately, so a consumer of the design system can load just
tokens.css + base.css + components.css without this site's doc chrome
or demo-only pattern CSS. Updated SKILL.md, README.md, index.md, and
install.md to describe the three-file consumer-facing split.
change
commit 2e167f08caf8ddc6aa5a2812bdfb1b0235912a93
author Claude <noreply@anthropic.com>
date
parent 5ff895e1
diff --git a/README.md b/README.md
index e68badc..b290fa7 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,9 @@ This is a small, personal project, so it is built as plainly as it can be:
   the values directly; there is no compiler in front of it.
 - `_sass/` holds the component and site-chrome CSS as plain, already-flat
   files (one per component group). `rake build` concatenates them in a fixed
-  order into `assets/css/style.css` — no Sass compiler involved.
+  order into four bundles — `base.css`, `components.css`, `docs.css`,
+  `patterns.css` — so a consumer can load just the design system without this
+  site's own chrome. No Sass compiler involved.
 - The documentation tables, swatches, and contrast figures are static
   markup, transcribed once from the token values rather than recomputed on
   every build.
@@ -52,7 +54,7 @@ $ bundle exec rake serve    # http://127.0.0.1:4000
 | Path | What it is |
 | --- | --- |
 | `assets/css/tokens.css` | Every color, type, space, radius, elevation, and motion value in the system, hand-maintained. |
-| `_sass/` | Plain CSS: base/reset, components (core/forms/feedback/navigation), and this documentation site's own chrome. Concatenated into `style.css` at build time. |
+| `_sass/` | Plain CSS: base/reset, components (core/forms/feedback/navigation), and this documentation site's own chrome. Concatenated into `base.css`, `components.css`, `docs.css`, and `patterns.css` at build time. |
 | `lib/build.rb` | The whole site builder in one file: a literal list of pages, front matter, ERB, and Kramdown. No collections config, no layout inheritance, no generic includes system — this is one specific site, not a framework. |
 | `_layouts/page.erb` | The one page shell (head, header, sidebar, footer). |
 | `_foundations/`, `_components/`, `_patterns/` | The documentation pages — static Markdown and HTML with a little ERB for links and nav. |
@@ -80,11 +82,12 @@ API. Change it there if the site ever moves off a project page.
 
 ## Using the CSS elsewhere
 
-Two files, in this order, and almost no JavaScript:
+Three files, in this order, and almost no JavaScript:
 
 ```html
 <link rel="stylesheet" href="tokens.css">
-<link rel="stylesheet" href="style.css">
+<link rel="stylesheet" href="base.css">
+<link rel="stylesheet" href="components.css">
 ```
 
 Retheming means overriding a handful of custom properties after `tokens.css`
diff --git a/SKILL.md b/SKILL.md
index 1074fd9..5e428bc 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -13,23 +13,22 @@ file repeats.
 
 ## Getting the CSS into another project
 
-Two files, in this order, no build step:
+Three files, in this order, no build step:
 
 ```html
 <link rel="stylesheet" href="tokens.css">
-<link rel="stylesheet" href="style.css">
+<link rel="stylesheet" href="base.css">
+<link rel="stylesheet" href="components.css">
 ```
 
-`tokens.css` is already exactly that file:
-[`assets/css/tokens.css`](assets/css/tokens.css). `style.css` is **not**
-this site's deployed `style.css` — that also bundles this documentation
-site's own chrome (`_sass/site/*.css`: the sidebar, the example-demo boxes,
-doc tables), which has nothing to do with the design system itself. Build
-the real one from just base + components:
-
-```console
-$ cat _sass/base/reset.css _sass/base/typography.css _sass/components/*.css > style.css
-```
+All three are already the exact files this site deploys:
+[`assets/css/tokens.css`](assets/css/tokens.css),
+[`assets/css/base.css`](assets/css/base.css),
+[`assets/css/components.css`](assets/css/components.css). This site also
+deploys `docs.css` and `patterns.css` — its own chrome (the sidebar, the
+example-demo boxes, doc tables) and the Loop/Archive pattern-page CSS — but
+neither has anything to do with the design system itself, so don't link
+them elsewhere.
 
 Load IBM Plex Mono separately — the system's one webfont:
 
diff --git a/_layouts/page.erb b/_layouts/page.erb
index 74ed742..8b33329 100644
--- a/_layouts/page.erb
+++ b/_layouts/page.erb
@@ -27,7 +27,10 @@
 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&display=swap">
 
 <link rel="stylesheet" href="<%= relative_url('/assets/css/tokens.css') %>">
-<link rel="stylesheet" href="<%= relative_url('/assets/css/style.css') %>">
+<link rel="stylesheet" href="<%= relative_url('/assets/css/base.css') %>">
+<link rel="stylesheet" href="<%= relative_url('/assets/css/components.css') %>">
+<link rel="stylesheet" href="<%= relative_url('/assets/css/docs.css') %>">
+<link rel="stylesheet" href="<%= relative_url('/assets/css/patterns.css') %>">
 <link rel="icon" href="<%= relative_url('/assets/favicon.svg') %>" type="image/svg+xml">
 
 <!-- Applied before first paint so an explicit theme choice never flashes. -->
diff --git a/index.md b/index.md
index 8b60c97..804faf4 100644
--- a/index.md
+++ b/index.md
@@ -134,12 +134,13 @@ empty state just states the fact: "Nothing tracked yet."
 
 ## Using it elsewhere
 
-Everything the system needs is two stylesheets and, for most components, no
+Everything the system needs is three stylesheets and, for most components, no
 JavaScript at all.
 
 ```html
 <link rel="stylesheet" href="tokens.css">
-<link rel="stylesheet" href="style.css">
+<link rel="stylesheet" href="base.css">
+<link rel="stylesheet" href="components.css">
 ```
 
 See [Using the CSS](<%= relative_url('/install/') %>) for the details,
diff --git a/install.md b/install.md
index 4264953..6a4efed 100644
--- a/install.md
+++ b/install.md
@@ -3,25 +3,30 @@ title: Using the CSS
 permalink: /install/
 section: Start here
 summary: >-
-  Two stylesheets, almost no JavaScript, no build step. Then a dozen custom
+  Three stylesheets, almost no JavaScript, no build step. Then a dozen custom
   properties if you want it to stop looking like this site.
 ---
 
-## The two files
+## The three files
 
-The system compiles to exactly two stylesheets. `tokens.css` is a
-hand-maintained block of custom properties; `style.css` is the components.
-The order matters — the components read the custom properties the tokens
-define.
+The system compiles to three stylesheets you'd actually reuse elsewhere.
+`tokens.css` is a hand-maintained block of custom properties; `base.css` is
+reset and typography; `components.css` is the components. The order
+matters — each file reads custom properties the one before it defines.
 
 ```html
 <link rel="stylesheet" href="tokens.css">
-<link rel="stylesheet" href="style.css">
+<link rel="stylesheet" href="base.css">
+<link rel="stylesheet" href="components.css">
 ```
 
-Both are on this site at
-[`/assets/css/tokens.css`](<%= relative_url('/assets/css/tokens.css') %>) and
-[`/assets/css/style.css`](<%= relative_url('/assets/css/style.css') %>).
+All three are on this site at
+[`/assets/css/tokens.css`](<%= relative_url('/assets/css/tokens.css') %>),
+[`/assets/css/base.css`](<%= relative_url('/assets/css/base.css') %>), and
+[`/assets/css/components.css`](<%= relative_url('/assets/css/components.css') %>).
+This site also loads `docs.css` and `patterns.css` — its own sidebar/header
+chrome and the Loop/Archive pattern-page CSS — but neither is part of the
+design system, so don't link them elsewhere.
 
 Load IBM Plex Mono separately — it is the system's one webfont, and nothing
 else is fetched:
@@ -101,7 +106,7 @@ $ bundle exec rake serve   # http://127.0.0.1:4000
     <thead><tr><th scope="col">Path</th><th scope="col">What it is</th></tr></thead>
     <tbody>
       <tr><td><code>assets/css/tokens.css</code></td><td>Every value in the system, hand-maintained.</td></tr>
-      <tr><td><code>_sass/</code></td><td>One plain CSS file per component group, concatenated into <code>style.css</code> at build time. No hexes, no pixels, no durations.</td></tr>
+      <tr><td><code>_sass/</code></td><td>One plain CSS file per component group, concatenated into <code>base.css</code>, <code>components.css</code>, <code>docs.css</code>, and <code>patterns.css</code> at build time (see <code>CSS_BUNDLES</code> in <code>lib/build.rb</code>). No hexes, no pixels, no durations.</td></tr>
       <tr><td><code>lib/build.rb</code></td><td>The whole site builder in one file — a literal list of pages, front matter, ERB, and Kramdown.</td></tr>
       <tr><td><code>_layouts/page.erb</code></td><td>The one page shell (head, header, sidebar, footer).</td></tr>
       <tr><td><code>_components/, _foundations/, _patterns/</code></td><td>Static Markdown and HTML — the content itself, hand-written.</td></tr>
diff --git a/lib/build.rb b/lib/build.rb
index 2a7bee1..82167ee 100644
--- a/lib/build.rb
+++ b/lib/build.rb
@@ -40,22 +40,26 @@ BASEURL     = "/arbitrary-definitions-design-system"
 REPOSITORY  = "kejadlen/arbitrary-definitions-design-system"
 LANG        = "en"
 
-# Plain CSS files, concatenated in this order into assets/css/style.css:
-# reset/base first, then components, then this site's own chrome.
-CSS_FILES = %w[
-  base/reset.css
-  base/typography.css
-  components/button.css
-  components/field.css
-  components/badge.css
-  components/card.css
-  components/feedback.css
-  components/tabs.css
-  site/shell.css
-  site/example.css
-  site/tokens-docs.css
-  site/patterns.css
-].freeze
+# Plain CSS files, concatenated into one output bundle per named group
+# (assets/css/<name>.css) rather than one monolithic style.css — a
+# consumer using this system elsewhere links tokens.css + base.css +
+# components.css and gets none of docs.css (this documentation site's own
+# chrome) or patterns.css (Loop/Archive's page-specific CSS, useful only
+# as a worked example). This site itself links all four, in this order.
+CSS_BUNDLES = {
+  "base" => %w[base/reset.css base/typography.css],
+  "components" => %w[
+    components/button.css
+    components/field.css
+    components/badge.css
+    components/card.css
+    components/feedback.css
+    components/tabs.css
+  ],
+  "docs" => %w[site/shell.css site/example.css site/tokens-docs.css],
+  "patterns" => %w[site/patterns.css],
+}.freeze
+CSS_BUNDLE_ORDER = %w[base components docs patterns].freeze
 
 # [source file (absolute or relative to ROOT), url, section label for the
 # doc-title header (nil to omit it entirely — index.md builds its own hero
@@ -127,10 +131,15 @@ def render_page(source_path, url, section)
 end
 
 def write_css
-  css = CSS_FILES.map { |name| File.read(File.join(ROOT, "_sass", name)) }.join("\n")
-  FileUtils.mkdir_p(File.join(SITE, "assets", "css"))
-  File.write(File.join(SITE, "assets", "css", "style.css"), css)
-  FileUtils.cp(File.join(ROOT, "assets", "css", "tokens.css"), File.join(SITE, "assets", "css", "tokens.css"))
+  out_dir = File.join(SITE, "assets", "css")
+  FileUtils.mkdir_p(out_dir)
+
+  CSS_BUNDLES.each do |bundle_name, files|
+    css = files.map { |name| File.read(File.join(ROOT, "_sass", name)) }.join("\n")
+    File.write(File.join(out_dir, "#{bundle_name}.css"), css)
+  end
+
+  FileUtils.cp(File.join(ROOT, "assets", "css", "tokens.css"), File.join(out_dir, "tokens.css"))
 end
 
 def copy_assets