book-kit 0.0.0-stage → 0.6.0

package/configs/markdownlint-cli2.jsonc

@@ -0,0 +1,98 @@
+// book-kit's base markdownlint config. The build merges lint.markdownlint
+// from book.config.yml (and its presets) into `config` (lib/lint.js); a book
+// with its own .markdownlint-cli2.jsonc uses that instead.
+{
+  "config": {
+    // Enable all default rules as baseline
+    "default": true,
+
+    // === Line and Formatting Rules ===
+    // Disable line length for prose-heavy content (books need flowing paragraphs)
+    "line-length": false,
+    // Allow chapters to start with H2 (H1 is reserved for book title)
+    "first-line-h1": false,
+
+    // === Heading Rules ===
+    // MD001: Heading levels should increment by one level at a time
+    "heading-increment": true,
+    // MD003: Heading style - use ATX style (hash marks)
+    "heading-style": { "style": "atx" },
+    // MD022: Headings should be surrounded by blank lines
+    "blanks-around-headings": true,
+    // MD024: Allow duplicate headings in different sections (common in books)
+    "no-duplicate-heading": { "siblings_only": true },
+    // MD025: Only one H1 per document (but we use H2 for chapters)
+    "single-h1": false,
+    // MD041: First line doesn't need to be H1 (chapters start with H2)
+    "first-line-heading": false,
+
+    // === List Rules ===
+    // MD004: Use dashes for unordered lists consistently
+    "ul-style": { "style": "dash" },
+    // MD005: Consistent list indentation
+    "list-indent": true,
+    // MD007: Unordered list indentation (2 spaces)
+    "ul-indent": { "indent": 2 },
+    // MD029: Ordered list item prefix (use ordered numbers)
+    "ol-prefix": { "style": "ordered" },
+    // MD030: Spaces after list markers
+    "list-marker-space": true,
+    // MD032: Lists should be surrounded by blank lines
+    "blanks-around-lists": true,
+
+    // === Link and Reference Rules ===
+    // Disable link fragment checking (custom anchor handling)
+    "link-fragments": false,
+    // MD034: Allow bare URLs when appropriate
+    "no-bare-urls": false,
+
+    // === HTML Rules ===
+    // Allow inline HTML for pandoc custom divs and spans
+    "no-inline-html": false,
+
+    // === Code Block Rules ===
+    // MD031: Code blocks should be surrounded by blank lines
+    "blanks-around-fences": true,
+    // MD040: Fenced code blocks should have a language specified
+    "fenced-code-language": false,
+    // MD046: Use fenced code blocks consistently
+    "code-block-style": { "style": "fenced" },
+    // MD048: Use backticks for code fences
+    "code-fence-style": { "style": "backtick" },
+
+    // === Whitespace Rules ===
+    // MD009: No trailing spaces (except for line breaks)
+    "no-trailing-spaces": { "br_spaces": 2 },
+    // MD010: No hard tabs
+    "no-hard-tabs": true,
+    // MD012: No multiple consecutive blank lines
+    "no-multiple-blanks": { "maximum": 1 },
+    // MD027: No multiple spaces after blockquote symbol
+    "no-multiple-space-blockquote": true,
+    // MD047: Files should end with a single newline
+    "single-trailing-newline": true,
+
+    // === Content Rules ===
+    // MD026: No trailing punctuation in headings (except ? for questions)
+    "no-trailing-punctuation": { "punctuation": ".,;:!" },
+    // MD036: No emphasis used as heading
+    "no-emphasis-as-heading": true,
+    // MD037: No spaces inside emphasis markers
+    "no-space-in-emphasis": true,
+    // MD038: No spaces inside code span elements
+    "no-space-in-code": true,
+    // MD039: No spaces inside link text
+    "no-space-in-links": true,
+    // MD045: Images should have alt text for accessibility
+    "no-alt-text": true,
+    // MD049: Use asterisks for emphasis consistently
+    "emphasis-style": { "style": "asterisk" },
+    // MD050: Use asterisks for strong consistently
+    "strong-style": { "style": "asterisk" }
+  },
+  // Ignore generated content (lib/lint.js adds drafts, structure.draft_suffix)
+  "ignores": [
+    "**/node_modules/**",
+    "**/dist/**"
+  ]
+}

package/configs/textlintrc.json

@@ -0,0 +1,22 @@
+{
+  "filters": {
+    "comments": true
+  },
+  "rules": {
+    "no-start-duplicated-conjunction": {
+      "interval": 2
+    },
+    "common-misspellings": {
+      "ignore": [
+        "doesnt",
+        "isnt"
+      ]
+    },
+    "diacritics": true,
+    "doubled-spaces": true,
+    "en-capitalization": false,
+    "@textlint-rule/no-unmatched-pair": true,
+    "@textlint-rule/no-duplicate-abbr": true,
+    "abbr-within-parentheses": true
+  }
+}

package/css/theme/01-tokens.css

@@ -0,0 +1,83 @@
+/* ============================================
+   THEME LAYER - Design Tokens & Variables
+   Using @theme for utility class generation
+   ============================================ */
+@theme {
+  /* ── Design Tokens ──────────────────────────────────────────────
+     These tokens generate Tailwind utility classes.
+     
+     Safe to modify:
+     • Brand colors (--color-brand, etc.) — used in screen CSS only
+     • Spacing scale (--spacing-*) — layout breathing room
+     • Line-height, paragraph spacing — reading comfort
+     
+     Format-dependent (change with care):
+     • Font families — must match @font-face declarations
+     • Callout colors — have corresponding dark-mode overrides
+     • Border radius — EPUB strips border-radius on some readers
+     ────────────────────────────────────────────────────────────── */
+
+  /* Book Typography - Source font family (Adobe, SIL Open Font License)
+     Source Serif 4: transitional serif with optical sizes, ideal for book body text
+     Source Sans 3: matching sans-serif for headings and callouts
+     Source Code Pro: matching monospace for code blocks */
+  --font-body: "Source Serif 4", "Source Serif 4 NotEqual", serif;
+  --font-heading: "Source Sans 3", sans-serif;
+  --font-mono: "Source Code Pro", "Courier New", monospace;
+  --font-emoji:
+    "Noto Color Emoji", "Apple Color Emoji", "Segoe UI Emoji", sans-serif;
+
+  /* Book Brand Colors */
+  --color-brand: #0056b3;
+  --color-muted: #6c757d;
+  --color-surface: #f8f9fa; /* Available for backgrounds */
+  --color-border: #dee2e6;
+  --color-emphasis: #495057;
+
+  /* Callout: Summary (TL;DR) */
+  --color-summary-bg: #f8f9fa;
+  --color-summary-border: #0056b3;
+
+  /* Callout: Tip */
+  --color-tip-bg: #f8f6f0;
+  --color-tip-accent: #b8956a;
+
+  /* Callout: Manager Guidance */
+  --color-manager-bg: #f0f4fa;
+  --color-manager-accent: #6a95c2;
+
+  /* Callout: IC Guidance */
+  --color-ic-bg: #f0f8f1;
+  --color-ic-accent: #6aaa6e;
+
+  /* Callout: Objection */
+  --color-objection-bg: #faf0f3;
+  --color-objection-accent: #b07090;
+
+  /* Core callouts (the kit defaults' note, tip, warning). Tip reuses the
+     Pro-Tip palette. */
+  --color-note-bg: #f5f7fa;
+  --color-note-accent: #8a9bb0;
+  --color-warning-bg: #fdf6e9;
+  --color-warning-accent: #c98a2b;
+
+  /* Callout: Takeaways */
+  --color-takeaway-bg: #f5f6f7;
+  --color-takeaway-border: #c8d4d9;
+
+  /* Print Grayscale Palette — Values used by @media print hardcoded rules */
+
+  /* Spacing Scale for Book Layout */
+  --spacing-callout: 1rem;
+  --spacing-section: 2rem;
+
+  /* Border Radius Scale */
+  --radius-callout: 0.375rem;
+
+  /* Book Typography Scale — Optimized for long-form reading */
+  --book-line-height: 1.6;
+  --book-paragraph-spacing: 0.75em;
+  --book-heading-line-height: 1.2;
+  --book-letter-spacing: normal;
+  --book-word-spacing: 0.02em;
+}

package/css/theme/02-fonts.css

@@ -0,0 +1,79 @@
+/* ============================================
+   FONT FACE DECLARATIONS
+   Source font family — variable WOFF2 with full OpenType features.
+   Source Serif 4: smcp, c2sc, onum, lnum, kern, liga, opsz (optical sizes)
+   Source Sans 3: kern, liga, pnum
+   Source Code Pro: frac, dnom, numr
+   Single file per style covers all weights 200-900.
+   ============================================ */
+
+/* Source Serif 4 — Body text (variable, Latin subset, optical sizes 8-60) */
+@font-face {
+  font-family: "Source Serif 4";
+  font-style: normal;
+  font-weight: 200 900;
+  font-display: swap;
+  src: url("../fonts/SourceSerif4-Variable-Latin.woff2") format("woff2");
+}
+@font-face {
+  font-family: "Source Serif 4";
+  font-style: italic;
+  font-weight: 200 900;
+  font-display: swap;
+  src: url("../fonts/SourceSerif4-Italic-Variable-Latin.woff2") format("woff2");
+}
+
+/* Source Serif 4 — ≠ only. The Latin subsets above lack U+2260, so a "≠"
+   in body text fell back to Georgia. Upstream Source Serif 4.005
+   (adobe-fonts/source-serif), subset to that one glyph. It's a separate
+   family, listed second in each serif stack: as an extra face of "Source
+   Serif 4", WeasyPrint embedded it under the main face's font name and drew
+   the wrong glyph in its place (a blank, or a "C"). */
+@font-face {
+  font-family: "Source Serif 4 NotEqual";
+  font-style: normal;
+  font-weight: 200 900;
+  font-display: swap;
+  src: url("../fonts/SourceSerif4-NotEqual.woff2") format("woff2");
+  unicode-range: U+2260;
+}
+@font-face {
+  font-family: "Source Serif 4 NotEqual";
+  font-style: italic;
+  font-weight: 200 900;
+  font-display: swap;
+  src: url("../fonts/SourceSerif4-Italic-NotEqual.woff2") format("woff2");
+  unicode-range: U+2260;
+}
+
+/* Source Sans 3 — Headings, callouts, UI elements (variable, Latin subset) */
+@font-face {
+  font-family: "Source Sans 3";
+  font-style: normal;
+  font-weight: 200 900;
+  font-display: swap;
+  src: url("../fonts/SourceSans3-Variable-Latin.woff2") format("woff2");
+}
+@font-face {
+  font-family: "Source Sans 3";
+  font-style: italic;
+  font-weight: 200 900;
+  font-display: swap;
+  src: url("../fonts/SourceSans3-Italic-Variable-Latin.woff2") format("woff2");
+}
+
+/* Source Code Pro — Code blocks, inline code (variable, Latin subset) */
+@font-face {
+  font-family: "Source Code Pro";
+  font-style: normal;
+  font-weight: 200 900;
+  font-display: swap;
+  src: url("../fonts/SourceCodePro-Variable-Latin.woff2") format("woff2");
+}
+@font-face {
+  font-family: "Source Code Pro";
+  font-style: italic;
+  font-weight: 200 900;
+  font-display: swap;
+  src: url("../fonts/SourceCodePro-Italic-Variable-Latin.woff2") format("woff2");
+}

package/css/theme/03-prose.css

@@ -0,0 +1,53 @@
+/* ============================================
+   TAILWIND TYPOGRAPHY - PROSE CONTAINER STYLES
+   Pandoc content should use class="prose" wrapper
+   for Typography descendant rules to activate.
+   ============================================ */
+
+/* Base prose configuration with book theme colors */
+.prose {
+  @apply prose-neutral max-w-none;
+  --tw-prose-body: var(--color-emphasis);
+  --tw-prose-headings: var(--color-emphasis);
+  --tw-prose-lead: var(--color-muted);
+  --tw-prose-links: var(--color-brand);
+  --tw-prose-bold: var(--color-emphasis);
+  --tw-prose-counters: var(--color-muted);
+  --tw-prose-bullets: var(--color-border);
+  --tw-prose-hr: var(--color-border);
+  --tw-prose-quotes: var(--color-emphasis);
+  --tw-prose-quote-borders: var(--color-muted);
+  --tw-prose-captions: var(--color-muted);
+  --tw-prose-code: var(--color-emphasis);
+  --tw-prose-pre-code: #1f2937;
+  --tw-prose-pre-bg: #f8f8f8;
+  --tw-prose-th-borders: var(--color-border);
+  --tw-prose-td-borders: var(--color-border);
+}
+
+/* Comfortable reading width on screen */
+@media screen {
+  .prose {
+    max-width: 40rem;
+    margin-left: auto;
+    margin-right: auto;
+    padding-left: 1.5rem;
+    padding-right: 1.5rem;
+  }
+}
+
+/* Larger text on medium screens */
+@media screen and (min-width: 768px) {
+  .prose {
+    @apply prose-lg;
+    max-width: 42rem;
+  }
+}
+
+/* Extra large text on wide screens */
+@media screen and (min-width: 1024px) {
+  .prose {
+    @apply prose-xl;
+    max-width: 44rem;
+  }
+}

package/css/theme/04-base.css

@@ -0,0 +1,226 @@
+/* ============================================
+   BASE LAYER - Element Resets & Typography
+   ============================================ */
+@layer base {
+  body {
+    font-family: var(--font-body);
+    font-optical-sizing: auto;
+    text-align: left;
+    line-height: var(--book-line-height);
+    letter-spacing: var(--book-letter-spacing);
+    word-spacing: var(--book-word-spacing);
+    font-kerning: normal;
+    font-variant-ligatures: common-ligatures contextual;
+    font-variant-numeric: oldstyle-nums proportional-nums;
+    text-rendering: optimizeLegibility;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+
+  /* Variable font weight for bold — 600 (semibold) gives better
+     color and texture than browser-default 700 with Source Serif 4. */
+  strong,
+  b {
+    font-weight: 600;
+  }
+
+  /* Paragraph typography for book readability */
+  p {
+    margin-bottom: var(--book-paragraph-spacing);
+    /* hanging-punctuation: Safari-only, stripped for EPUB compatibility */
+    hanging-punctuation: first allow-end last;
+  }
+
+  /* Heading Hierarchy — clear visual distinction at every level */
+  h1 {
+    font-family: var(--font-heading);
+    font-size: 2.25rem;
+    font-weight: 700;
+    line-height: var(--book-heading-line-height);
+    margin-top: 0;
+    margin-bottom: 1.25rem;
+    letter-spacing: normal;
+    page-break-after: avoid;
+    page-break-inside: avoid;
+    orphans: 3;
+    widows: 3;
+  }
+
+  h2 {
+    font-family: var(--font-heading);
+    font-size: 1.75rem;
+    font-weight: 700;
+    line-height: var(--book-heading-line-height);
+    margin-top: 2.5rem;
+    margin-bottom: 0.75rem;
+    letter-spacing: normal;
+    page-break-after: avoid;
+    page-break-inside: avoid;
+    orphans: 3;
+    widows: 3;
+  }
+
+  h3 {
+    font-family: var(--font-heading);
+    font-size: 1.35rem;
+    font-weight: 700;
+    line-height: var(--book-heading-line-height);
+    margin-top: 2rem;
+    margin-bottom: 0.5rem;
+    letter-spacing: normal;
+    page-break-after: avoid;
+    page-break-inside: avoid;
+    orphans: 3;
+    widows: 3;
+  }
+
+  h4 {
+    font-family: var(--font-heading);
+    font-size: 1.15rem;
+    font-weight: 700;
+    line-height: var(--book-heading-line-height);
+    margin-top: 1.5rem;
+    margin-bottom: 0.35rem;
+    letter-spacing: normal;
+    orphans: 2;
+    widows: 2;
+    page-break-after: avoid;
+    page-break-inside: avoid;
+  }
+
+  h5 {
+    font-family: var(--font-heading);
+    font-size: 1rem;
+    font-weight: 700;
+    line-height: var(--book-heading-line-height);
+    margin-top: 1.25rem;
+    margin-bottom: 0.25rem;
+    letter-spacing: 0.07em;
+    text-transform: uppercase;
+    orphans: 2;
+    widows: 2;
+    page-break-after: avoid;
+    page-break-inside: avoid;
+  }
+
+  h6 {
+    font-family: var(--font-heading);
+    font-size: 0.95rem;
+    font-weight: 700;
+    line-height: var(--book-heading-line-height);
+    margin-top: 1rem;
+    margin-bottom: 0.25rem;
+    letter-spacing: normal;
+    font-style: italic;
+    orphans: 2;
+    widows: 2;
+    page-break-after: avoid;
+    page-break-inside: avoid;
+  }
+
+  /* Navigation and TOC */
+  nav {
+    page-break-after: avoid;
+  }
+
+  #TOC {
+    page-break-inside: auto;
+  }
+
+  #TOC li {
+    list-style: none;
+    margin-bottom: 0.4em;
+    line-height: 1.4;
+  }
+
+  #TOC a {
+    color: inherit;
+    text-decoration: none;
+    margin-bottom: 0.2em;
+  }
+
+  /* Page numbers in TOC — CSS Paged Media, print/PDF only.
+     Scoped here so strip-page-rules.js naturally excludes it from EPUB
+     (target-counter is unsupported by Kindle and all e-readers). */
+  @media print {
+    #TOC a {
+      display: flex;
+      justify-content: space-between;
+      align-items: baseline;
+      padding-right: 0;
+    }
+
+    #TOC a::after {
+      content: target-counter(attr(href), page);
+      flex-shrink: 0;
+      margin-left: auto;
+      font-weight: normal;
+      white-space: nowrap;
+      font-family: var(--font-heading);
+      font-variant-numeric: lining-nums tabular-nums;
+      text-align: right;
+      width: 2.5em;
+    }
+  }
+
+  #TOC ul {
+    padding-left: 1.5rem;
+  }
+
+  #TOC > ul {
+    padding-left: 0.75rem;
+    padding-right: 0.75rem;
+  }
+
+  /* Top-level TOC entries (section headings) get extra weight */
+  #TOC > ul > li {
+    margin-bottom: 0.6em;
+    font-weight: 500;
+  }
+
+  /* Nested TOC entries (chapter titles) */
+  #TOC > ul > li > ul > li {
+    font-weight: 400;
+    font-size: 0.95em;
+  }
+
+  /* Small caps strategy:
+     • Screen: OpenType smcp/c2sc glyphs at natural size (no compensation)
+     • Print: font-size: inherit — Source Serif 4 provides real smcp glyphs
+     • EPUB: font-size: 1.05em compensation — e-readers often synthesize
+       small caps by scaling down uppercase, which renders shorter than
+       true OpenType glyphs. 1.05em brings visual height closer to x-height. */
+
+  /* Small Caps for Acronyms 
+   * IMPORTANT: Do NOT add font-size reduction here.
+   * all-small-caps renders at x-height (matching lowercase).
+   * Adding font-size < 1em would make small caps shorter than lowercase letters.
+   */
+  span.smallcaps {
+    font-variant-caps: all-small-caps;
+    letter-spacing: 0.05em;
+  }
+
+  /* Title Block Elements */
+  p.author,
+  p.subtitle,
+  p.date {
+    font-family: var(--font-heading);
+  }
+
+  h1.title,
+  p.author,
+  p.subtitle,
+  p.date,
+  div.rights {
+    text-align: center;
+  }
+
+  p.subtitle {
+    font-size: 1.15rem;
+    font-weight: 300;
+    line-height: 1.5;
+    font-style: italic;
+    color: var(--color-muted);
+  }
+}