docpensieve 0.1.2 → 0.1.4

package/starter/02-components/08-logo-icon.mdx

@@ -27,6 +27,8 @@ folder. Nothing can leave it: a page does not read the rest of the machine.
 
 Placed in a text, the icon takes its size and colour.
 
+<ForTheme framework="tailwind">
+
 <div className="text-indigo-600 text-2xl">
   <LogoIcon src="./icons/star.svg" /> at the size and colour of the text
 </div>
@@ -35,38 +37,64 @@ Placed in a text, the icon takes its size and colour.
   <LogoIcon src="./icons/star.svg" /> and here, smaller and greyer
 </div>
 
+</ForTheme>
+<ForTheme framework="custom">
+
+<div className="accent-text large">
+  <LogoIcon src="./icons/star.svg" /> at the size and colour of the text
+</div>
+
+<div className="small muted">
+  <LogoIcon src="./icons/star.svg" /> and here, smaller and greyer
+</div>
+
+</ForTheme>
+
 ## Sizes
 
 `size` accepts any CSS length.
 
-<div className="flex items-end gap-4 text-emerald-600">
+<div style={{ display: 'flex', alignItems: 'flex-end', gap: '1rem', color: '#10b981' }}>
   <LogoIcon src="./icons/shield.svg" size="1rem" />
   <LogoIcon src="./icons/shield.svg" size="2rem" />
   <LogoIcon src="./icons/shield.svg" size="3rem" />
   <LogoIcon src="./icons/shield.svg" size="4rem" />
 </div>
 
+<ForTheme framework="tailwind">
+
+```mdx
+<LogoIcon src="./icons/shield.svg" size="3rem" style={{ color: '#10b981' }} />
+```
+
+</ForTheme>
+<ForTheme framework="custom">
+
 ```mdx
-<LogoIcon src="./icons/shield.svg" size="3rem" className="text-emerald-600" />
+<LogoIcon src="./icons/shield.svg" size="3rem" className="green" />
 ```
 
+`green` comes from `theme/99-docpensieve.css`, and sets `color`.
+
+</ForTheme>
+
 The colour only follows if the file relies on `currentColor` rather than on a
 fixed colour.
 
 ## In a list
 
-<ul className="list-none pl-0 space-y-2">
-  <li className="flex items-center gap-2">
-    <LogoIcon src="./icons/lightning.svg" size="1.1rem" className="text-amber-500" /> No script to
+<ul style={{ listStyle: 'none', paddingInlineStart: 0, display: 'grid', gap: '0.5rem' }}>
+  <li style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+    <LogoIcon src="./icons/lightning.svg" size="1.1rem" style={{ color: '#f59e0b' }} /> No script to
     load
   </li>
-  <li className="flex items-center gap-2">
-    <LogoIcon src="./icons/shield.svg" size="1.1rem" className="text-emerald-600" /> Links are read
+  <li style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+    <LogoIcon src="./icons/shield.svg" size="1.1rem" style={{ color: '#10b981' }} /> Links are read
     back before publishing
   </li>
-  <li className="flex items-center gap-2">
-    <LogoIcon src="./icons/book.svg" size="1.1rem" className="text-indigo-600" /> One version per
-    branch
+  <li style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+    <LogoIcon src="./icons/book.svg" size="1.1rem" style={{ color: 'var(--dp-accent)' }} /> One
+    version per branch
   </li>
 </ul>
 
@@ -74,10 +102,10 @@ fixed colour.
 
 <Columns>
   <Column span={6}>
-    <Card className="h-full">
+    <Card style={{ height: '100%' }}>
       <CardBody>
-        <LogoIcon src="./icons/lightning.svg" size="1.6rem" className="text-amber-500" />
-        <strong className="block mt-2 mb-1 text-base font-semibold">Fast</strong>
+        <LogoIcon src="./icons/lightning.svg" size="1.6rem" style={{ color: '#f59e0b' }} />
+        <strong style={{ display: 'block', margin: '0.5rem 0 0.25rem', fontSize: '1rem' }}>Fast</strong>
 
         No hydration, no bundle to download before reading.
       </CardBody>
@@ -85,10 +113,10 @@ fixed colour.
 
   </Column>
   <Column span={6}>
-    <Card className="h-full">
+    <Card style={{ height: '100%' }}>
       <CardBody>
-        <LogoIcon src="./icons/shield.svg" size="1.6rem" className="text-emerald-600" />
-        <strong className="block mt-2 mb-1 text-base font-semibold">Verified</strong>
+        <LogoIcon src="./icons/shield.svg" size="1.6rem" style={{ color: '#10b981' }} />
+        <strong style={{ display: 'block', margin: '0.5rem 0 0.25rem', fontSize: '1rem' }}>Verified</strong>
 
         Dead links and invalid markup stop the publication.
       </CardBody>

package/starter/02-components/09-for-theme.mdx

@@ -0,0 +1,45 @@
+---
+title: ForTheme
+description: Content kept for one theme only.
+---
+
+# ForTheme
+
+Keeps its content for the sites whose theme matches. The choice is made at
+build time: the other variant does not even reach the HTML.
+
+```mdx
+<ForTheme framework="tailwind">
+
+With Tailwind, a utility: `className="max-w-sm"`.
+
+</ForTheme>
+<ForTheme framework="custom">
+
+With the custom theme, a class of the `theme/` folder: `className="narrow"`.
+
+</ForTheme>
+```
+
+It is how the pages of this documentation show each example in the terms of
+your theme. Changing `theme.framework` in the configuration changes what they
+show, without editing them.
+
+## On this site
+
+<ForTheme framework="tailwind">
+
+This site is built with the **Tailwind** theme.
+
+</ForTheme>
+<ForTheme framework="custom">
+
+This site is built with the **custom** theme.
+
+</ForTheme>
+
+## What it refuses
+
+A `framework` other than `tailwind` or `custom` stops the build, with the
+accepted values: a typo would otherwise hide the content under every theme,
+without a word.

package/starter/02-components/{index.md → index.mdx}

@@ -8,7 +8,12 @@ description: The components available in every page, without an import.
 These components can be used in any `.mdx` page **without an import**.
 
 They provide the **structure** — wrappers, separators, spacing. The look is set
-with `className`, in utilities of the active theme:
+with `className`.
+
+<ForTheme framework="tailwind">
+
+With the Tailwind theme, a `className` holds utilities, compiled from the ones
+your pages use:
 
 ```mdx
 <Card className="max-w-sm">
@@ -19,6 +24,43 @@ with `className`, in utilities of the active theme:
 The component classes live in the `components` layer, below the utilities: a
 `className` set at use always wins.
 
+</ForTheme>
+<ForTheme framework="custom">
+
+With the custom theme, a `className` names classes of your own: there are no
+utilities. Every `.css` file of the `theme/` folder, at the root of the
+project, is appended to the stylesheet, and `docpensieve dev` picks up every
+change.
+
+```mdx
+<Card className="narrow">
+  <CardHeader className="centered">Title</CardHeader>
+</Card>
+```
+
+```css
+/* theme/custom.css */
+.narrow {
+  max-inline-size: 24rem;
+}
+
+.centered {
+  text-align: center;
+}
+```
+
+The component classes live in the `components` layer, those of the theme
+folder in none: a class of yours always wins.
+
+The examples of these pages use the classes of `theme/99-docpensieve.css`,
+which `init` wrote next to this documentation: delete both together.
+
+</ForTheme>
+
+Every example is shown in the terms of the site's theme, through
+[ForTheme](./for-theme/): changing `theme.framework` in the configuration
+changes the examples too.
+
 ## Available
 
 - [Card](./card/) — card, with header, body, footer and image
@@ -29,6 +71,7 @@ The component classes live in the `components` layer, below the utilities: a
 - [ScrollToTop](./scroll-to-top/) — back to the top of the page
 - [Skill](./skill/) — level gauge
 - [LogoIcon](./logo-icon/) — SVG icon inlined in the page
+- [ForTheme](./for-theme/) — content kept for one theme only
 
 ## Without JavaScript
 

package/starter/03-reference/01-cli.md

@@ -35,11 +35,21 @@ npx docpensieve init [dir]
 
 Without `--force`, the command refuses to overwrite an existing configuration.
 
+Without an interactive terminal — a script, continuous integration, or a
+terminal that gives the programs it runs no interactive input — the command
+asks nothing: it says so, then sticks to the options and the defaults. `--yes`
+makes that choice explicit and silences the notice.
+
 Unless `--minimal` is given, the command installs DocPensieve's documentation
 in the new site, in `docs/<version>/99-docpensieve/`: a **DocPensieve** section
 at the end of the menu, matching the installed version. Delete that folder when
 you no longer need it.
 
+Under the `custom` theme, the command also writes `theme/custom.css`, where the
+project's own classes go, and — with the documentation —
+`theme/99-docpensieve.css`, the classes of its examples, to delete along with
+it. An existing `theme/custom.css` is never overwritten, even with `--force`.
+
 ## `build`
 
 Generates the site.

package/starter/03-reference/02-configuration.md

@@ -103,6 +103,11 @@ theme: {
 
 The available tokens are listed in [Themes](../guide/themes/).
 
+Longer rules go in the `theme/` folder, at the root of the project: every
+`.css` file in it is appended after `css`, in name order, and
+`docpensieve dev` picks up every change. Under the `custom` theme, `init`
+starts it with `theme/custom.css`.
+
 ## `baseUrl`, and why you rarely write it
 
 A `siteUrl` with a sub-path already gives it: `https://example.com/my-project`

package/starter/03-reference/04-theme.md

@@ -124,7 +124,8 @@ The delivered stylesheet is assembled from four pieces, in this order:
 | a skin or a bridge  | `custom.css`, or `tailwind-bridge.css`             |
 | the components' one | The `dp-*` rules of the shipped components         |
 
-Then comes what the project adds through `theme.css`.
+Then comes what the project adds: `theme.css`, then every `.css` file of its
+`theme/` folder, in name order.
 
 The layout is **never** duplicated in a provider: it lives in `structure.css`,
 which both share. A provider only takes care of the styling.
@@ -144,6 +145,6 @@ The `custom` theme has no utility layer: its stylesheets are in no layer, and
 therefore come before the component rules, which stay in the `components`
 layer.
 
-What `theme.css` adds is in no layer: without a layer, a rule wins over all
-those that have one. That is what lets you write a fix there without worrying
+What `theme.css` and the `theme/` folder add is in no layer: without a layer, a
+rule wins over all those that have one. That is what lets you write a fix there without worrying
 about specificity.

package/starter/examples.css

@@ -0,0 +1,156 @@
+/*
+ * Classes of the documentation's examples, for the custom theme.
+ *
+ * The custom theme loads no utility framework: the classes a page uses are
+ * written by the project. These are the ones DocPensieve's own pages use.
+ * "docpensieve init" installs this file as theme/99-docpensieve.css, next to
+ * the documentation in 99-docpensieve/: delete both together.
+ *
+ * Every colour comes from the --dp-* tokens, or is mixed with them, so that
+ * the examples follow the light and dark palettes.
+ */
+
+/* Sizes */
+
+.narrow {
+  max-inline-size: 24rem;
+}
+
+.full-height {
+  block-size: 100%;
+}
+
+/* Text */
+
+.centered {
+  text-align: center;
+}
+
+.small {
+  font-size: 0.875rem;
+}
+
+.large {
+  font-size: 1.5rem;
+}
+
+.caps {
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.italic {
+  font-style: italic;
+}
+
+.muted {
+  color: var(--dp-text-soft);
+}
+
+.accent-text {
+  color: var(--dp-accent);
+}
+
+.figure {
+  font-size: 2.25rem;
+  font-weight: 600;
+  line-height: 1.2;
+  color: var(--dp-accent);
+}
+
+.label {
+  display: block;
+  margin-block: 0.5rem 0.25rem;
+  font-size: 1rem;
+  font-weight: 600;
+}
+
+/* Colours, for the text and the gauges alike */
+
+.green {
+  --dp-skill-color: #10b981;
+  color: #10b981;
+}
+
+.amber {
+  --dp-skill-color: #f59e0b;
+  color: #f59e0b;
+}
+
+/* Cards */
+
+.highlight {
+  border-color: var(--dp-accent);
+  background: var(--dp-accent-soft);
+}
+
+.warning {
+  border-color: #f59e0b;
+  background: color-mix(in oklab, #f59e0b 12%, var(--dp-bg));
+}
+
+.warning-title {
+  color: color-mix(in oklab, #d97706 70%, var(--dp-text));
+}
+
+.plain {
+  border: 0;
+  box-shadow: none;
+  background: transparent;
+}
+
+.flush {
+  padding-inline: 0;
+}
+
+/* Layout */
+
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.row.align-end {
+  align-items: flex-end;
+}
+
+.plain-list {
+  display: grid;
+  gap: 0.5rem;
+  padding-inline-start: 0;
+  list-style: none;
+}
+
+.wide-gap {
+  gap: 2.5rem;
+}
+
+/* Content that flows from one column to the next, as in a newspaper */
+
+.flow {
+  columns: 2;
+  column-gap: 1.5rem;
+}
+
+@media (min-width: 40rem) {
+  .flow {
+    columns: 3;
+  }
+}
+
+.flow > * {
+  break-inside: avoid;
+  margin-block-end: 1.5rem;
+}
+
+/* A back-to-top button placed in the text rather than fixed on the screen */
+
+.inline-button {
+  position: static;
+  display: inline-flex;
+  inline-size: auto;
+  box-shadow: none;
+  padding-inline: 1rem;
+}

package/types/theme.d.ts

@@ -4,14 +4,24 @@
  * @module docpensieve/theme
  */
 import { ThemeEngine } from '@docpensieve/theme';
+/**
+ * Reads the project's own stylesheets: every `.css` file of its `theme/`
+ * folder, in name order. None when the folder does not exist.
+ *
+ * @param {string} [rootDir] Project root.
+ * @returns {string[]} The contents of each file.
+ */
+export declare function projectCss(rootDir?: string): string[];
 /**
  * Mounts the ThemeEngine matching the declared framework.
  *
  * The CLI does this wiring: `core` deliberately ignores the `theme` package
  * and receives the engine by injection (ADR-002).
  *
- * Along the way, the class table is handed to the components: that is what
- * lets them ask for their class instead of hard-coding it (ADR-007).
+ * Along the way, the class table and the framework are handed to the
+ * components: that is what lets them ask for their class instead of
+ * hard-coding it (ADR-007), and lets `ForTheme` keep the variant of the active
+ * theme.
  *
  * @param {Record<string, any>} config Normalised configuration.
  * @param {string} [extraCss] CSS appended after the theme's — the look of the