kitfly 0.1.2 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (209) hide show
  1. package/CHANGELOG.md +46 -0
  2. package/README.md +63 -16
  3. package/VERSION +1 -1
  4. package/dist/_raw/content/deployment/preflight.md +134 -0
  5. package/dist/_raw/content/deployment/recipes/aws-s3.md +128 -0
  6. package/dist/_raw/content/deployment/recipes/cloudflare-pages.md +73 -0
  7. package/dist/_raw/content/deployment/recipes/cloudflare-r2.md +156 -0
  8. package/dist/_raw/content/deployment/recipes/fly-io.md +57 -0
  9. package/dist/_raw/content/deployment/recipes/github-pages.md +112 -0
  10. package/dist/_raw/content/deployment/recipes/netlify.md +99 -0
  11. package/dist/_raw/content/deployment/recipes/vercel.md +88 -0
  12. package/dist/_raw/content/deployment/secrets-and-env-vars.md +75 -0
  13. package/dist/_raw/content/deployment.md +128 -0
  14. package/dist/_raw/content/guide/approaches.md +182 -0
  15. package/dist/_raw/content/guide/features.md +121 -0
  16. package/dist/_raw/content/guide/getting-started.md +112 -0
  17. package/dist/_raw/content/guide/kitfly-overview.md +209 -0
  18. package/dist/_raw/content/reference/configuration.md +259 -0
  19. package/dist/_raw/content/reference/design-catalog.md +167 -0
  20. package/dist/_raw/content/reference/environment-variables.md +66 -0
  21. package/dist/_raw/content/reference/glossary.md +92 -0
  22. package/dist/_raw/content/reference/key-concepts.md +118 -0
  23. package/dist/_raw/content/reference/plugins.md +220 -0
  24. package/dist/_raw/content/reference/slides-authoring-guidelines.md +129 -0
  25. package/dist/_raw/content/reference/structure.md +166 -0
  26. package/dist/_raw/content/reference.md +20 -0
  27. package/dist/_raw/content/templates/crucible.md +192 -0
  28. package/dist/_raw/content/templates/handbook.md +83 -0
  29. package/dist/_raw/content/templates/minimal.md +138 -0
  30. package/dist/_raw/content/templates/overview.md +187 -0
  31. package/dist/_raw/content/templates/pipeline.md +151 -0
  32. package/dist/_raw/content/templates/productbook.md +187 -0
  33. package/dist/_raw/content/templates/runbook.md +193 -0
  34. package/dist/_raw/content/templates/servicebook.md +163 -0
  35. package/dist/_raw/docs/decisions/ADR-0001-minimalist-site-code.md +118 -0
  36. package/dist/_raw/docs/decisions/ADR-0002-ai-accessibility.md +153 -0
  37. package/dist/_raw/docs/decisions/ADR-0003-single-file-bundle.md +93 -0
  38. package/dist/_raw/docs/decisions/ADR-0004-bun-runtime.md +98 -0
  39. package/dist/_raw/docs/decisions/ADR-0005-plugin-contract-and-distribution.md +110 -0
  40. package/dist/_raw/docs/decisions/DDR-0001-viewport-locked-layout.md +111 -0
  41. package/dist/_raw/docs/decisions/DDR-0002-theme-system.md +131 -0
  42. package/dist/_raw/docs/decisions/DDR-0003-bounded-logo-slot.md +106 -0
  43. package/dist/_raw/docs/decisions/DDR-0004-slides-rendering-model.md +113 -0
  44. package/dist/_raw/docs/decisions/DDR-0005-deterministic-layout-boundary.md +107 -0
  45. package/dist/_raw/docs/userguide/cli/build.md +85 -0
  46. package/dist/_raw/docs/userguide/cli/bundle.md +81 -0
  47. package/dist/_raw/docs/userguide/cli/dev.md +92 -0
  48. package/dist/_raw/docs/userguide/cli/init.md +116 -0
  49. package/dist/_raw/docs/userguide/cli/servers.md +69 -0
  50. package/dist/_raw/docs/userguide/cli/stop.md +76 -0
  51. package/dist/_raw/docs/userguide/cli/update.md +78 -0
  52. package/dist/_raw/docs/userguide/cli/version.md +65 -0
  53. package/dist/_raw/docs/userguide/cli.md +34 -0
  54. package/dist/_raw/docs/userguide/sharing.md +94 -0
  55. package/dist/_raw/schemas/plugin-schemas-notes.md +71 -0
  56. package/dist/_raw/schemas.md +42 -0
  57. package/dist/assets/brand/kitfly-favicon-32.png +0 -0
  58. package/dist/assets/brand/kitfly-icon-64.png +0 -0
  59. package/dist/assets/brand/kitfly-logo-128.png +0 -0
  60. package/dist/assets/brand/kitfly-logo-512.png +0 -0
  61. package/dist/assets/brand/kitfly-logo.svg +12132 -0
  62. package/dist/assets/brand/kitfly-neon-128.png +0 -0
  63. package/dist/assets/brand/kitfly-neon-192.png +0 -0
  64. package/dist/assets/brand/kitfly-neon-256.png +0 -0
  65. package/dist/assets/brand/kitfly-neon.png +0 -0
  66. package/dist/assets/brand/palette.md +75 -0
  67. package/dist/content/deployment/index.html +11 -0
  68. package/dist/content/deployment/preflight.html +418 -0
  69. package/dist/content/deployment/recipes/aws-s3.html +421 -0
  70. package/dist/content/deployment/recipes/cloudflare-pages.html +372 -0
  71. package/dist/content/deployment/recipes/cloudflare-r2.html +443 -0
  72. package/dist/content/deployment/recipes/fly-io.html +356 -0
  73. package/dist/content/deployment/recipes/github-pages.html +414 -0
  74. package/dist/content/deployment/recipes/index.html +11 -0
  75. package/dist/content/deployment/recipes/netlify.html +394 -0
  76. package/dist/content/deployment/recipes/vercel.html +382 -0
  77. package/dist/content/deployment/secrets-and-env-vars.html +380 -0
  78. package/dist/content/deployment.html +426 -0
  79. package/dist/content/guide/approaches.html +501 -0
  80. package/dist/content/guide/features.html +436 -0
  81. package/dist/content/guide/getting-started.html +403 -0
  82. package/dist/content/guide/index.html +11 -0
  83. package/dist/content/guide/kitfly-overview.html +544 -0
  84. package/dist/content/index.html +11 -0
  85. package/dist/content/reference/configuration.html +580 -0
  86. package/dist/content/reference/design-catalog.html +449 -0
  87. package/dist/content/reference/environment-variables.html +367 -0
  88. package/dist/content/reference/glossary.html +368 -0
  89. package/dist/content/reference/index.html +11 -0
  90. package/dist/content/reference/key-concepts.html +399 -0
  91. package/dist/content/reference/plugins.html +491 -0
  92. package/dist/content/reference/slides-authoring-guidelines.html +418 -0
  93. package/dist/content/reference/structure.html +463 -0
  94. package/dist/content/reference.html +335 -0
  95. package/dist/content/templates/crucible.html +546 -0
  96. package/dist/content/templates/handbook.html +405 -0
  97. package/dist/content/templates/index.html +11 -0
  98. package/dist/content/templates/minimal.html +447 -0
  99. package/dist/content/templates/overview.html +558 -0
  100. package/dist/content/templates/pipeline.html +494 -0
  101. package/dist/content/templates/productbook.html +540 -0
  102. package/dist/content/templates/runbook.html +543 -0
  103. package/dist/content/templates/servicebook.html +523 -0
  104. package/dist/content-index.json +549 -0
  105. package/dist/docs/decisions/ADR-0001-minimalist-site-code.html +491 -0
  106. package/dist/docs/decisions/ADR-0002-ai-accessibility.html +434 -0
  107. package/dist/docs/decisions/ADR-0003-single-file-bundle.html +412 -0
  108. package/dist/docs/decisions/ADR-0004-bun-runtime.html +409 -0
  109. package/dist/docs/decisions/ADR-0005-plugin-contract-and-distribution.html +402 -0
  110. package/dist/docs/decisions/DDR-0001-viewport-locked-layout.html +459 -0
  111. package/dist/docs/decisions/DDR-0002-theme-system.html +452 -0
  112. package/dist/docs/decisions/DDR-0003-bounded-logo-slot.html +423 -0
  113. package/dist/docs/decisions/DDR-0004-slides-rendering-model.html +399 -0
  114. package/dist/docs/decisions/DDR-0005-deterministic-layout-boundary.html +422 -0
  115. package/dist/docs/decisions/index.html +11 -0
  116. package/dist/docs/userguide/cli/build.html +408 -0
  117. package/dist/docs/userguide/cli/bundle.html +419 -0
  118. package/dist/docs/userguide/cli/dev.html +428 -0
  119. package/dist/docs/userguide/cli/index.html +11 -0
  120. package/dist/docs/userguide/cli/init.html +436 -0
  121. package/dist/docs/userguide/cli/servers.html +393 -0
  122. package/dist/docs/userguide/cli/stop.html +408 -0
  123. package/dist/docs/userguide/cli/update.html +406 -0
  124. package/dist/docs/userguide/cli/version.html +406 -0
  125. package/dist/docs/userguide/cli.html +386 -0
  126. package/dist/docs/userguide/index.html +11 -0
  127. package/dist/docs/userguide/sharing.html +465 -0
  128. package/dist/index.html +387 -0
  129. package/dist/llms.txt +18 -0
  130. package/dist/provenance.json +7 -0
  131. package/dist/schemas/index.html +11 -0
  132. package/dist/schemas/plugin-registry.schema.html +327 -0
  133. package/dist/schemas/plugin-schemas-notes.html +364 -0
  134. package/dist/schemas/plugin.schema.html +327 -0
  135. package/dist/schemas/plugins.schema.html +327 -0
  136. package/dist/schemas/v0/common.schema.html +386 -0
  137. package/dist/schemas/v0/index.html +11 -0
  138. package/dist/schemas/v0/plugin-registry.schema.html +547 -0
  139. package/dist/schemas/v0/plugin.schema.html +497 -0
  140. package/dist/schemas/v0/plugins.schema.html +406 -0
  141. package/dist/schemas/v0/site.schema.html +541 -0
  142. package/dist/schemas/v0/theme.schema.html +615 -0
  143. package/dist/schemas.html +351 -0
  144. package/dist/styles.css +1262 -0
  145. package/package.json +4 -2
  146. package/plugins-dist/callouts.css +32 -0
  147. package/plugins-dist/callouts.js +46 -0
  148. package/plugins-dist/slides-visuals.css +390 -0
  149. package/plugins-dist/slides-visuals.js +689 -0
  150. package/registry/plugins.yaml +35 -0
  151. package/schemas/README.md +10 -0
  152. package/schemas/plugin-registry.schema.json +5 -0
  153. package/schemas/plugin-schemas-notes.md +71 -0
  154. package/schemas/plugin.schema.json +5 -0
  155. package/schemas/plugins.schema.json +5 -0
  156. package/schemas/v0/common.schema.json +64 -0
  157. package/schemas/v0/plugin-registry.schema.json +225 -0
  158. package/schemas/v0/plugin.schema.json +175 -0
  159. package/schemas/v0/plugins.schema.json +84 -0
  160. package/schemas/v0/site.schema.json +56 -9
  161. package/schemas/v0/theme.schema.json +105 -22
  162. package/scripts/build.ts +158 -3
  163. package/scripts/bundle.ts +261 -95
  164. package/scripts/dev.ts +301 -11
  165. package/src/__tests__/build.test.ts +220 -1
  166. package/src/__tests__/bundle.test.ts +31 -0
  167. package/src/__tests__/cli.test.ts +14 -3
  168. package/src/__tests__/dev-plugin-errors.test.ts +20 -0
  169. package/src/__tests__/fixtures/fences/slides-visuals/invalid/bad-list-indent.md +5 -0
  170. package/src/__tests__/fixtures/fences/slides-visuals/invalid/blank-line.md +5 -0
  171. package/src/__tests__/fixtures/fences/slides-visuals/invalid/compare-object-items.md +9 -0
  172. package/src/__tests__/fixtures/fences/slides-visuals/invalid/flow-branching-no-source.md +5 -0
  173. package/src/__tests__/fixtures/fences/slides-visuals/invalid/flow-converging-no-target.md +6 -0
  174. package/src/__tests__/fixtures/fences/slides-visuals/invalid/indented-fence.md +4 -0
  175. package/src/__tests__/fixtures/fences/slides-visuals/invalid/staircase-empty-steps.md +3 -0
  176. package/src/__tests__/fixtures/fences/slides-visuals/invalid/stat-grid-missing-fields.md +5 -0
  177. package/src/__tests__/fixtures/fences/slides-visuals/invalid/timeline-horizontal-no-events.md +2 -0
  178. package/src/__tests__/fixtures/fences/slides-visuals/invalid/unknown-type.md +3 -0
  179. package/src/__tests__/fixtures/fences/slides-visuals/valid/compare.md +10 -0
  180. package/src/__tests__/fixtures/fences/slides-visuals/valid/comparison-table.md +14 -0
  181. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-branching-no-split.md +7 -0
  182. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-branching.md +8 -0
  183. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-converging-no-merge.md +7 -0
  184. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-converging.md +8 -0
  185. package/src/__tests__/fixtures/fences/slides-visuals/valid/funnel.md +7 -0
  186. package/src/__tests__/fixtures/fences/slides-visuals/valid/kpi.md +5 -0
  187. package/src/__tests__/fixtures/fences/slides-visuals/valid/layer-cake.md +6 -0
  188. package/src/__tests__/fixtures/fences/slides-visuals/valid/pyramid.md +6 -0
  189. package/src/__tests__/fixtures/fences/slides-visuals/valid/quadrant-grid.md +8 -0
  190. package/src/__tests__/fixtures/fences/slides-visuals/valid/scorecard.md +13 -0
  191. package/src/__tests__/fixtures/fences/slides-visuals/valid/staircase-down.md +7 -0
  192. package/src/__tests__/fixtures/fences/slides-visuals/valid/staircase.md +8 -0
  193. package/src/__tests__/fixtures/fences/slides-visuals/valid/stat-grid.md +8 -0
  194. package/src/__tests__/fixtures/fences/slides-visuals/valid/timeline-horizontal.md +9 -0
  195. package/src/__tests__/fixtures/fences/slides-visuals/valid/timeline-vertical.md +10 -0
  196. package/src/__tests__/init.test.ts +35 -0
  197. package/src/__tests__/plugin-loader.test.ts +221 -0
  198. package/src/__tests__/shared.test.ts +451 -0
  199. package/src/__tests__/slides-visuals-fence-contract.test.ts +28 -0
  200. package/src/__tests__/slides-visuals-runtime-regressions.bun.test.ts +147 -0
  201. package/src/__tests__/styles.test.ts +35 -0
  202. package/src/cli.ts +9 -4
  203. package/src/plugin-loader.ts +245 -0
  204. package/src/shared.ts +650 -7
  205. package/src/site/styles.css +331 -0
  206. package/src/site/template.html +66 -5
  207. package/src/templates/deck.ts +186 -0
  208. package/src/templates/driver.ts +11 -1
  209. package/src/templates/minimal.ts +1 -0
package/dist/content/reference/slides-authoring-guidelines.html ADDED
@@ -0,0 +1,418 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>Slides Authoring Guidelines - Kitfly Docs</title>
7
+ <link rel="icon" type="image/png" sizes="32x32" href="../../assets/brand/kitfly-favicon-32.png">
8
+ <link rel="icon" type="image/png" sizes="64x64" href="../../assets/brand/kitfly-neon-256.png">
9
+ <link rel="stylesheet" href="../../styles.css">
10
+ <style id="kitfly-theme">
11
+ :root { --color-bg: #ffffff;
12
+ --color-bg-sidebar: #f5f7f8;
13
+ --color-text: #374151;
14
+ --color-text-muted: #6b7280;
15
+ --color-border: #e5e7eb;
16
+ --color-link: #007182;
17
+ --color-link-hover: #0a6172;
18
+ --color-accent: #152F46;
19
+ --color-code-bg: #f5f7f8;
20
+ --color-logo: #152F46;
21
+ --sidebar-width: 280px;
22
+ --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
23
+ --font-headings: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
24
+ --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace; }
25
+ html { font-size: 16px; }
26
+ @media (prefers-color-scheme: dark) {
27
+ :root:not([data-theme="light"]) { --color-bg: #0d1117;
28
+ --color-bg-sidebar: #152F46;
29
+ --color-text: #e5e7eb;
30
+ --color-text-muted: #9ca3af;
31
+ --color-border: #374151;
32
+ --color-link: #709EA6;
33
+ --color-link-hover: #8fb5bc;
34
+ --color-accent: #f9fafb;
35
+ --color-code-bg: #152F46;
36
+ --color-logo: #f9fafb; }
37
+ }
38
+ [data-theme="dark"] { --color-bg: #0d1117;
39
+ --color-bg-sidebar: #152F46;
40
+ --color-text: #e5e7eb;
41
+ --color-text-muted: #9ca3af;
42
+ --color-border: #374151;
43
+ --color-link: #709EA6;
44
+ --color-link-hover: #8fb5bc;
45
+ --color-accent: #f9fafb;
46
+ --color-code-bg: #152F46;
47
+ --color-logo: #f9fafb; }
48
+ [data-theme="light"] { --color-bg: #ffffff;
49
+ --color-bg-sidebar: #f5f7f8;
50
+ --color-text: #374151;
51
+ --color-text-muted: #6b7280;
52
+ --color-border: #e5e7eb;
53
+ --color-link: #007182;
54
+ --color-link-hover: #0a6172;
55
+ --color-accent: #152F46;
56
+ --color-code-bg: #f5f7f8;
57
+ --color-logo: #152F46;
58
+ --sidebar-width: 280px;
59
+ --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
60
+ --font-headings: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
61
+ --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace; }
62
+ </style>
63
+ <!-- Syntax highlighting - Prism.js -->
64
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1/themes/prism.min.css" id="prism-light">
65
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1/themes/prism-okaidia.min.css" id="prism-dark" disabled>
66
+
67
+ <script>
68
+ // Apply saved theme immediately to prevent flash
69
+ (function() {
70
+ const saved = localStorage.getItem('theme');
71
+ if (saved) {
72
+ document.documentElement.setAttribute('data-theme', saved);
73
+ }
74
+ // Set Prism theme based on saved or system preference
75
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
76
+ const isDark = saved === 'dark' || (!saved && prefersDark);
77
+ if (isDark) {
78
+ document.getElementById('prism-light')?.setAttribute('disabled', '');
79
+ document.getElementById('prism-dark')?.removeAttribute('disabled');
80
+ }
81
+ })();
82
+ </script>
83
+ </head>
84
+ <body class="mode-docs">
85
+ <div class="mobile-header">
86
+ <button class="nav-toggle" onclick="toggleNav()" aria-label="Toggle navigation">
87
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
88
+ <path d="M3 12h18M3 6h18M3 18h18"/>
89
+ </svg>
90
+ </button>
91
+ <a href="../../" class="mobile-logo" title="Home" data-initial="K">
92
+ <img src="../../assets/brand/kitfly-neon-256.png" alt="Kitfly" class="logo-img logo-icon" onerror="this.onerror=null;this.style.display='none';this.parentElement.classList.add('logo-fallback')"/>
93
+ </a>
94
+ <button class="mobile-theme-toggle" onclick="toggleTheme()" title="Toggle theme" aria-label="Toggle theme">
95
+ <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
96
+ <circle cx="12" cy="12" r="5"/>
97
+ <path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/>
98
+ </svg>
99
+ <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
100
+ <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
101
+ </svg>
102
+ </button>
103
+ </div>
104
+ <div class="layout">
105
+ <nav class="sidebar">
106
+ <div class="sidebar-header">
107
+ <div class="logo logo-icon">
108
+ <a href="/" class="logo-icon" data-initial="K">
109
+ <img src="../../assets/brand/kitfly-neon-256.png" alt="Kitfly" class="logo-img" onerror="this.onerror=null;this.style.display='none';this.parentElement.classList.add('logo-fallback')"/>
110
+ </a>
111
+ <span class="logo-text">
112
+ <a href="/" class="brand">Kitfly</a>
113
+ <a href="../../" class="product">Kitfly Docs</a>
114
+ </span>
115
+ </div>
116
+ <div class="header-tools">
117
+ <button class="theme-toggle" onclick="toggleTheme()" title="Toggle theme" aria-label="Toggle theme">
118
+ <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
119
+ <circle cx="12" cy="12" r="5"/>
120
+ <path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/>
121
+ </svg>
122
+ <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
123
+ <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
124
+ </svg>
125
+ </button>
126
+ <div class="sidebar-meta">
127
+ <span class="meta-version">v0.2.1</span>
128
+ <span class="meta-branch">HEAD</span>
129
+ </div>
130
+ </div>
131
+ </div>
132
+ <div class="sidebar-nav">
133
+ <ul><li><a href="../../index.html" class="nav-home">Home</a></li><li><span class="nav-section">Guide</span><ul><li><a href="../../content/guide/approaches.html">approaches</a></li><li><a href="../../content/guide/features.html">features</a></li><li><a href="../../content/guide/getting-started.html">getting-started</a></li><li><a href="../../content/guide/kitfly-overview.html">kitfly-overview</a></li></ul></li><li><span class="nav-section">Templates</span><ul><li><a href="../../content/templates/crucible.html">crucible</a></li><li><a href="../../content/templates/handbook.html">handbook</a></li><li><a href="../../content/templates/minimal.html">minimal</a></li><li><a href="../../content/templates/overview.html">overview</a></li><li><a href="../../content/templates/pipeline.html">pipeline</a></li><li><a href="../../content/templates/productbook.html">productbook</a></li><li><a href="../../content/templates/runbook.html">runbook</a></li><li><a href="../../content/templates/servicebook.html">servicebook</a></li></ul></li><li><a href="../../content/reference.html" class="nav-section">Reference</a><ul><li><a href="../../content/reference/configuration.html">configuration</a></li><li><a href="../../content/reference/design-catalog.html">design-catalog</a></li><li><a href="../../content/reference/environment-variables.html">environment-variables</a></li><li><a href="../../content/reference/glossary.html">glossary</a></li><li><a href="../../content/reference/key-concepts.html">key-concepts</a></li><li><a href="../../content/reference/plugins.html">plugins</a></li><li><a href="../../content/reference/slides-authoring-guidelines.html" class="active">slides-authoring-guidelines</a></li><li><a href="../../content/reference/structure.html">structure</a></li></ul></li><li><a href="../../content/deployment.html" class="nav-section">Deployment</a><ul><li><a href="../../content/deployment/preflight.html">preflight</a></li><li><details><summary class="nav-group">recipes</summary><ul><li><a href="../../content/deployment/recipes/aws-s3.html">aws-s3</a></li><li><a href="../../content/deployment/recipes/cloudflare-pages.html">cloudflare-pages</a></li><li><a href="../../content/deployment/recipes/cloudflare-r2.html">cloudflare-r2</a></li><li><a href="../../content/deployment/recipes/fly-io.html">fly-io</a></li><li><a href="../../content/deployment/recipes/github-pages.html">github-pages</a></li><li><a href="../../content/deployment/recipes/netlify.html">netlify</a></li><li><a href="../../content/deployment/recipes/vercel.html">vercel</a></li></ul></details></li><li><a href="../../content/deployment/secrets-and-env-vars.html">secrets-and-env-vars</a></li></ul></li><li><span class="nav-section">User Guide</span><ul><li><details><summary class="nav-group"><a href="../../docs/userguide/cli.html">cli</a></summary><ul><li><a href="../../docs/userguide/cli/build.html">build</a></li><li><a href="../../docs/userguide/cli/bundle.html">bundle</a></li><li><a href="../../docs/userguide/cli/dev.html">dev</a></li><li><a href="../../docs/userguide/cli/init.html">init</a></li><li><a href="../../docs/userguide/cli/servers.html">servers</a></li><li><a href="../../docs/userguide/cli/stop.html">stop</a></li><li><a href="../../docs/userguide/cli/update.html">update</a></li><li><a href="../../docs/userguide/cli/version.html">version</a></li></ul></details></li><li><a href="../../docs/userguide/sharing.html">sharing</a></li></ul></li><li><span class="nav-section">Decisions</span><ul><li><a href="../../docs/decisions/ADR-0001-minimalist-site-code.html">ADR-0001-minimalist-site-code</a></li><li><a href="../../docs/decisions/ADR-0002-ai-accessibility.html">ADR-0002-ai-accessibility</a></li><li><a href="../../docs/decisions/ADR-0003-single-file-bundle.html">ADR-0003-single-file-bundle</a></li><li><a href="../../docs/decisions/ADR-0004-bun-runtime.html">ADR-0004-bun-runtime</a></li><li><a href="../../docs/decisions/ADR-0005-plugin-contract-and-distribution.html">ADR-0005-plugin-contract-and-distribution</a></li><li><a href="../../docs/decisions/DDR-0001-viewport-locked-layout.html">DDR-0001-viewport-locked-layout</a></li><li><a href="../../docs/decisions/DDR-0002-theme-system.html">DDR-0002-theme-system</a></li><li><a href="../../docs/decisions/DDR-0003-bounded-logo-slot.html">DDR-0003-bounded-logo-slot</a></li><li><a href="../../docs/decisions/DDR-0004-slides-rendering-model.html">DDR-0004-slides-rendering-model</a></li><li><a href="../../docs/decisions/DDR-0005-deterministic-layout-boundary.html">DDR-0005-deterministic-layout-boundary</a></li></ul></li><li><a href="../../schemas.html" class="nav-section">Schemas</a><ul><li><a href="../../schemas/plugin-registry.schema.html">plugin-registry.schema</a></li><li><a href="../../schemas/plugin-schemas-notes.html">plugin-schemas-notes</a></li><li><a href="../../schemas/plugin.schema.html">plugin.schema</a></li><li><a href="../../schemas/plugins.schema.html">plugins.schema</a></li><li><details><summary class="nav-group">v0</summary><ul><li><a href="../../schemas/v0/common.schema.html">common.schema</a></li><li><a href="../../schemas/v0/plugin-registry.schema.html">plugin-registry.schema</a></li><li><a href="../../schemas/v0/plugin.schema.html">plugin.schema</a></li><li><a href="../../schemas/v0/plugins.schema.html">plugins.schema</a></li><li><a href="../../schemas/v0/site.schema.html">site.schema</a></li><li><a href="../../schemas/v0/theme.schema.html">theme.schema</a></li></ul></details></li></ul></li></ul>
134
+ </div>
135
+ </nav>
136
+ <main class="content">
137
+ <article class="prose">
138
+ <nav class="breadcrumbs"><a href="../../content/guide/approaches.html">Content</a><span class="separator">›</span><a href="../../content/reference/configuration.html">Reference</a><span class="separator">›</span><span>slides-authoring-guidelines</span></nav>
139
+ <div class="page-meta">Last updated: 2026-02-15</div>
140
+ <h1 id="slides-authoring-guidelines">Slides Authoring Guidelines</h1>
141
+ <p>This page is for slide authors and AI agents generating slide content.</p>
142
+ <p>Goal: avoid common layouts that look broken but are actually content-density issues.</p>
143
+ <h2 id="quick-rules">Quick rules</h2>
144
+ <ul>
145
+ <li>Keep vertical visuals short. If a slide is tall and busy, trim items before adding more styling.</li>
146
+ <li>Treat highlighted (<code>.accent</code>) blocks as emphasis, not interaction.</li>
147
+ <li>Scroll in slides mode is allowed for dense content. Prefer no scroll for presentation slides.</li>
148
+ </ul>
149
+ <h2 id="df-006-single-accent-in-block-grid-looks-like-a-tab">DF-006: Single <code>.accent</code> in <code>.block-grid</code> looks like a tab</h2>
150
+ <h3 id="problem">Problem</h3>
151
+ <p>When one block in a row is accented and others are not, users read it as a selected tab and expect click behavior.</p>
152
+ <h3 id="do-this">Do this</h3>
153
+ <ul>
154
+ <li>In one grid row, accent all blocks or accent none.</li>
155
+ <li>If you need real tabs, treat that as a future widget (<code>slides-widgets</code>), not static blocks.</li>
156
+ </ul>
157
+ <h3 id="avoid-this">Avoid this</h3>
158
+ <pre><code class="language-html">&lt;div class=&quot;block-grid cols-3&quot;&gt;
159
+ &lt;div class=&quot;block&quot;&gt;Backend&lt;/div&gt;
160
+ &lt;div class=&quot;block accent&quot;&gt;Platform&lt;/div&gt;
161
+ &lt;div class=&quot;block&quot;&gt;SRE&lt;/div&gt;
162
+ &lt;/div&gt;
163
+ </code></pre>
164
+ <h3 id="prefer-this">Prefer this</h3>
165
+ <pre><code class="language-html">&lt;div class=&quot;block-grid cols-3&quot;&gt;
166
+ &lt;div class=&quot;block accent&quot;&gt;Backend&lt;/div&gt;
167
+ &lt;div class=&quot;block accent&quot;&gt;Platform&lt;/div&gt;
168
+ &lt;div class=&quot;block accent&quot;&gt;SRE&lt;/div&gt;
169
+ &lt;/div&gt;
170
+ </code></pre>
171
+ <p>or</p>
172
+ <pre><code class="language-html">&lt;div class=&quot;block-grid cols-3&quot;&gt;
173
+ &lt;div class=&quot;block&quot;&gt;Backend&lt;/div&gt;
174
+ &lt;div class=&quot;block&quot;&gt;Platform&lt;/div&gt;
175
+ &lt;div class=&quot;block&quot;&gt;SRE&lt;/div&gt;
176
+ &lt;/div&gt;
177
+ </code></pre>
178
+ <h2 id="df-007-block-flowvertical-can-overflow-at-43">DF-007: <code>block-flow.vertical</code> can overflow at 4/3</h2>
179
+ <h3 id="problem">Problem</h3>
180
+ <p><code>.block-flow.vertical</code> (HTML: <code>class=&quot;block-flow vertical&quot;</code>) with 4 steps can exceed the visible frame at <code>4/3</code>.</p>
181
+ <h3 id="do-this">Do this</h3>
182
+ <ul>
183
+ <li>At <code>4/3</code>: limit vertical flows to 3 blocks.</li>
184
+ <li>At <code>16/9</code>: 4 blocks is usually fine.</li>
185
+ <li>If the slide also has extra text/callouts, reduce steps further.</li>
186
+ </ul>
187
+ <h3 id="guidance">Guidance</h3>
188
+ <ul>
189
+ <li>If you must keep all steps, scroll is acceptable.</li>
190
+ <li>For presentation-first slides, split into two slides instead.</li>
191
+ </ul>
192
+ <h3 id="example-target">Example target</h3>
193
+ <pre><code class="language-html">&lt;div class=&quot;block-flow vertical&quot;&gt;
194
+ &lt;div class=&quot;block&quot;&gt;1. Intake&lt;/div&gt;
195
+ &lt;div class=&quot;block&quot;&gt;2. Validate&lt;/div&gt;
196
+ &lt;div class=&quot;block&quot;&gt;3. Ship&lt;/div&gt;
197
+ &lt;/div&gt;
198
+ </code></pre>
199
+ <h2 id="df-014-timeline-vertical-callout-can-clip-at-169">DF-014: <code>timeline-vertical</code> + callout can clip at 16/9</h2>
200
+ <h3 id="problem">Problem</h3>
201
+ <p>A 5-event vertical timeline plus a callout often exceeds the frame at <code>16/9</code>.</p>
202
+ <h3 id="do-this">Do this</h3>
203
+ <ul>
204
+ <li>At <code>16/9</code>: keep <code>timeline-vertical</code> to 4 events when the slide also has a callout.</li>
205
+ <li>At <code>4/3</code>: keep to 3 events with a callout.</li>
206
+ <li>If you need all events, remove the callout or move it to a follow-up slide.</li>
207
+ </ul>
208
+ <h3 id="example-safe-with-callout">Example (safe with callout)</h3>
209
+ <pre><code class="language-text">:::timeline-vertical
210
+ events:
211
+ - label: &quot;Detect&quot;
212
+ date: &quot;09:15&quot;
213
+ - label: &quot;Triage&quot;
214
+ date: &quot;09:24&quot;
215
+ - label: &quot;Mitigate&quot;
216
+ date: &quot;09:42&quot;
217
+ - label: &quot;Recover&quot;
218
+ date: &quot;10:08&quot;
219
+ :::
220
+
221
+ &gt; WARNING: External API fallback remained active for 12 minutes.
222
+ </code></pre>
223
+ <h2 id="aspect-ratio-checklist">Aspect ratio checklist</h2>
224
+ <ul>
225
+ <li><code>16/9</code>: medium density, but still cap long vertical stacks.</li>
226
+ <li><code>4/3</code>: tighter vertical budget. Reduce stacked items first.</li>
227
+ <li><code>16/10</code>: between <code>16/9</code> and <code>4/3</code>; apply the same conservative limits when callouts are present.</li>
228
+ </ul>
229
+ <h2 id="summary">Summary</h2>
230
+ <p>These are authoring constraints, not renderer bugs. When a slide clips:</p>
231
+ <ol>
232
+ <li>Reduce vertical item count.</li>
233
+ <li>Remove or move callouts.</li>
234
+ <li>Split dense content across two slides.</li>
235
+ </ol>
236
+
237
+ </article>
238
+ <aside class="toc"><span class="toc-title">On this page</span><ul><li><a href="#quick-rules">Quick rules</a></li><li class="toc-h3"><a href="#problem">Problem</a></li><li class="toc-h3"><a href="#do-this">Do this</a></li><li class="toc-h3"><a href="#avoid-this">Avoid this</a></li><li class="toc-h3"><a href="#prefer-this">Prefer this</a></li><li class="toc-h3"><a href="#problem">Problem</a></li><li class="toc-h3"><a href="#do-this">Do this</a></li><li class="toc-h3"><a href="#guidance">Guidance</a></li><li class="toc-h3"><a href="#example-target">Example target</a></li><li class="toc-h3"><a href="#problem">Problem</a></li><li class="toc-h3"><a href="#do-this">Do this</a></li><li class="toc-h3"><a href="#example-safe-with-callout">Example (safe with callout)</a></li><li><a href="#aspect-ratio-checklist">Aspect ratio checklist</a></li><li><a href="#summary">Summary</a></li></ul></aside>
239
+ </main>
240
+ </div>
241
+
242
+ <footer class="site-footer">
243
+ <div class="footer-content">
244
+ <div class="footer-left">
245
+ <span class="footer-version">v0.2.1</span>
246
+ <span class="footer-separator">·</span>
247
+ <span class="footer-commit" title="Commit: 30dfc01">Published 2026-02-15</span>
248
+ </div>
249
+ <div class="footer-center">
250
+ <span class="footer-copyright"><a href="https://3leaps.net" class="footer-link">© 2026 3 Leaps, LLC</a></span>
251
+ <span class="footer-separator">·</span><a href="/" class="footer-link">Kitfly</a>
252
+ </div>
253
+ <div class="footer-right">
254
+ <a href="https://kitfly.dev" class="footer-link">Built with Kitfly</a>
255
+ </div>
256
+ </div>
257
+ </footer>
258
+ <!-- Syntax highlighting - Prism.js -->
259
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js"></script>
260
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/plugins/autoloader/prism-autoloader.min.js"></script>
261
+ <!-- Mermaid diagram support -->
262
+ <script type="module">
263
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
264
+
265
+ function getMermaidTheme() {
266
+ const theme = document.documentElement.getAttribute('data-theme');
267
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
268
+ const isDark = theme === 'dark' || (!theme && prefersDark);
269
+ return isDark ? 'dark' : 'neutral';
270
+ }
271
+
272
+ mermaid.initialize({
273
+ startOnLoad: true,
274
+ theme: getMermaidTheme()
275
+ });
276
+
277
+ // Re-render mermaid diagrams when theme changes
278
+ window.reinitMermaid = async function() {
279
+ mermaid.initialize({ startOnLoad: false, theme: getMermaidTheme() });
280
+ const diagrams = document.querySelectorAll('.mermaid');
281
+ for (const el of diagrams) {
282
+ const code = el.getAttribute('data-mermaid-source');
283
+ if (code) {
284
+ el.innerHTML = code;
285
+ el.removeAttribute('data-processed');
286
+ }
287
+ }
288
+ await mermaid.run({ nodes: diagrams });
289
+ };
290
+ </script>
291
+
292
+ <script>
293
+ function toggleTheme() {
294
+ const html = document.documentElement;
295
+ const current = html.getAttribute('data-theme');
296
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
297
+
298
+ let next;
299
+ if (current === 'dark') {
300
+ next = 'light';
301
+ } else if (current === 'light') {
302
+ next = 'dark';
303
+ } else {
304
+ // No explicit theme set, toggle from system preference
305
+ next = prefersDark ? 'light' : 'dark';
306
+ }
307
+
308
+ html.setAttribute('data-theme', next);
309
+ localStorage.setItem('theme', next);
310
+
311
+ // Switch Prism theme
312
+ const prismLight = document.getElementById('prism-light');
313
+ const prismDark = document.getElementById('prism-dark');
314
+ if (next === 'dark') {
315
+ prismLight?.setAttribute('disabled', '');
316
+ prismDark?.removeAttribute('disabled');
317
+ } else {
318
+ prismLight?.removeAttribute('disabled');
319
+ prismDark?.setAttribute('disabled', '');
320
+ }
321
+
322
+ // Re-render mermaid diagrams with new theme
323
+ if (window.reinitMermaid) {
324
+ window.reinitMermaid();
325
+ }
326
+ }
327
+
328
+ // Slides mode hash routing
329
+ (function initSlidesMode() {
330
+ const shell = document.querySelector('.slides-shell');
331
+ if (!shell) return;
332
+
333
+ const slides = Array.from(document.querySelectorAll('.slide'));
334
+ if (!slides.length) return;
335
+
336
+ const prevBtn = document.querySelector('.slide-prev');
337
+ const nextBtn = document.querySelector('.slide-next');
338
+ const counter = document.querySelector('.slide-counter');
339
+ const progressBar = document.querySelector('.slide-progress-bar');
340
+ const navLinks = Array.from(document.querySelectorAll('.sidebar-nav a[href^="#slide-"]'));
341
+ let current = 0;
342
+
343
+ function setActive(n) {
344
+ current = Math.max(0, Math.min(n, slides.length - 1));
345
+ slides.forEach((slide, idx) => slide.classList.toggle('active', idx === current));
346
+ navLinks.forEach((link) => {
347
+ const active = link.getAttribute('href') === '#' + slides[current].id;
348
+ link.classList.toggle('active', active);
349
+ });
350
+ if (counter) counter.textContent = (current + 1) + ' / ' + slides.length;
351
+ if (progressBar) progressBar.style.width = (((current + 1) / slides.length) * 100) + '%';
352
+ if (prevBtn) prevBtn.disabled = current === 0;
353
+ if (nextBtn) nextBtn.disabled = current === slides.length - 1;
354
+ history.replaceState(null, '', '#' + slides[current].id);
355
+ }
356
+
357
+ function setFromHash() {
358
+ const hash = window.location.hash || '';
359
+ const idx = slides.findIndex((s) => '#' + s.id === hash);
360
+ if (idx >= 0) setActive(idx);
361
+ else setActive(0);
362
+ }
363
+
364
+ prevBtn?.addEventListener('click', () => setActive(current - 1));
365
+ nextBtn?.addEventListener('click', () => setActive(current + 1));
366
+
367
+ document.addEventListener('keydown', (e) => {
368
+ if (e.key === 'ArrowRight' || e.key === ' ') {
369
+ e.preventDefault();
370
+ setActive(current + 1);
371
+ } else if (e.key === 'ArrowLeft') {
372
+ e.preventDefault();
373
+ setActive(current - 1);
374
+ } else if (e.key === 'Home') {
375
+ e.preventDefault();
376
+ setActive(0);
377
+ } else if (e.key === 'End') {
378
+ e.preventDefault();
379
+ setActive(slides.length - 1);
380
+ }
381
+ });
382
+
383
+ window.addEventListener('hashchange', setFromHash);
384
+ setFromHash();
385
+ })();
386
+
387
+ // Copy code button
388
+ document.querySelectorAll('.prose pre code').forEach(block => {
389
+ const button = document.createElement('button');
390
+ button.className = 'copy-button';
391
+ button.textContent = 'Copy';
392
+ button.onclick = async () => {
393
+ await navigator.clipboard.writeText(block.textContent);
394
+ button.textContent = 'Copied!';
395
+ setTimeout(() => button.textContent = 'Copy', 2000);
396
+ };
397
+ block.parentElement.appendChild(button);
398
+ });
399
+
400
+ // Mobile nav toggle
401
+ function toggleNav() {
402
+ document.querySelector('.sidebar').classList.toggle('open');
403
+ }
404
+
405
+ // Close nav when clicking outside on mobile
406
+ document.addEventListener('click', (e) => {
407
+ const sidebar = document.querySelector('.sidebar');
408
+ const toggle = document.querySelector('.nav-toggle');
409
+ if (sidebar.classList.contains('open') &&
410
+ !sidebar.contains(e.target) &&
411
+ !toggle.contains(e.target)) {
412
+ sidebar.classList.remove('open');
413
+ }
414
+ });
415
+ </script>
416
+
417
+ </body>
418
+ </html>