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.
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