kitfly 0.1.2 → 0.2.0

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 (194) hide show
  1. package/CHANGELOG.md +34 -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/structure.md +166 -0
  25. package/dist/_raw/content/reference.md +19 -0
  26. package/dist/_raw/content/templates/crucible.md +192 -0
  27. package/dist/_raw/content/templates/handbook.md +83 -0
  28. package/dist/_raw/content/templates/minimal.md +138 -0
  29. package/dist/_raw/content/templates/overview.md +187 -0
  30. package/dist/_raw/content/templates/pipeline.md +151 -0
  31. package/dist/_raw/content/templates/productbook.md +187 -0
  32. package/dist/_raw/content/templates/runbook.md +193 -0
  33. package/dist/_raw/content/templates/servicebook.md +163 -0
  34. package/dist/_raw/docs/decisions/ADR-0001-minimalist-site-code.md +118 -0
  35. package/dist/_raw/docs/decisions/ADR-0002-ai-accessibility.md +153 -0
  36. package/dist/_raw/docs/decisions/ADR-0003-single-file-bundle.md +93 -0
  37. package/dist/_raw/docs/decisions/ADR-0004-bun-runtime.md +98 -0
  38. package/dist/_raw/docs/decisions/ADR-0005-plugin-contract-and-distribution.md +110 -0
  39. package/dist/_raw/docs/decisions/DDR-0001-viewport-locked-layout.md +111 -0
  40. package/dist/_raw/docs/decisions/DDR-0002-theme-system.md +131 -0
  41. package/dist/_raw/docs/decisions/DDR-0003-bounded-logo-slot.md +106 -0
  42. package/dist/_raw/docs/decisions/DDR-0004-slides-rendering-model.md +113 -0
  43. package/dist/_raw/docs/decisions/DDR-0005-deterministic-layout-boundary.md +107 -0
  44. package/dist/_raw/docs/userguide/cli/build.md +85 -0
  45. package/dist/_raw/docs/userguide/cli/bundle.md +81 -0
  46. package/dist/_raw/docs/userguide/cli/dev.md +92 -0
  47. package/dist/_raw/docs/userguide/cli/init.md +116 -0
  48. package/dist/_raw/docs/userguide/cli/servers.md +69 -0
  49. package/dist/_raw/docs/userguide/cli/stop.md +76 -0
  50. package/dist/_raw/docs/userguide/cli/update.md +78 -0
  51. package/dist/_raw/docs/userguide/cli/version.md +65 -0
  52. package/dist/_raw/docs/userguide/cli.md +34 -0
  53. package/dist/_raw/docs/userguide/sharing.md +94 -0
  54. package/dist/_raw/schemas/plugin-schemas-notes.md +71 -0
  55. package/dist/_raw/schemas.md +42 -0
  56. package/dist/assets/brand/kitfly-favicon-32.png +0 -0
  57. package/dist/assets/brand/kitfly-icon-64.png +0 -0
  58. package/dist/assets/brand/kitfly-logo-128.png +0 -0
  59. package/dist/assets/brand/kitfly-logo-512.png +0 -0
  60. package/dist/assets/brand/kitfly-logo.svg +12132 -0
  61. package/dist/assets/brand/kitfly-neon-128.png +0 -0
  62. package/dist/assets/brand/kitfly-neon-192.png +0 -0
  63. package/dist/assets/brand/kitfly-neon-256.png +0 -0
  64. package/dist/assets/brand/kitfly-neon.png +0 -0
  65. package/dist/assets/brand/palette.md +75 -0
  66. package/dist/content/deployment/index.html +11 -0
  67. package/dist/content/deployment/preflight.html +418 -0
  68. package/dist/content/deployment/recipes/aws-s3.html +421 -0
  69. package/dist/content/deployment/recipes/cloudflare-pages.html +372 -0
  70. package/dist/content/deployment/recipes/cloudflare-r2.html +443 -0
  71. package/dist/content/deployment/recipes/fly-io.html +356 -0
  72. package/dist/content/deployment/recipes/github-pages.html +414 -0
  73. package/dist/content/deployment/recipes/index.html +11 -0
  74. package/dist/content/deployment/recipes/netlify.html +394 -0
  75. package/dist/content/deployment/recipes/vercel.html +382 -0
  76. package/dist/content/deployment/secrets-and-env-vars.html +380 -0
  77. package/dist/content/deployment.html +426 -0
  78. package/dist/content/guide/approaches.html +501 -0
  79. package/dist/content/guide/features.html +436 -0
  80. package/dist/content/guide/getting-started.html +403 -0
  81. package/dist/content/guide/index.html +11 -0
  82. package/dist/content/guide/kitfly-overview.html +544 -0
  83. package/dist/content/index.html +11 -0
  84. package/dist/content/reference/configuration.html +580 -0
  85. package/dist/content/reference/design-catalog.html +449 -0
  86. package/dist/content/reference/environment-variables.html +367 -0
  87. package/dist/content/reference/glossary.html +368 -0
  88. package/dist/content/reference/index.html +11 -0
  89. package/dist/content/reference/key-concepts.html +399 -0
  90. package/dist/content/reference/plugins.html +491 -0
  91. package/dist/content/reference/structure.html +463 -0
  92. package/dist/content/reference.html +334 -0
  93. package/dist/content/templates/crucible.html +546 -0
  94. package/dist/content/templates/handbook.html +405 -0
  95. package/dist/content/templates/index.html +11 -0
  96. package/dist/content/templates/minimal.html +447 -0
  97. package/dist/content/templates/overview.html +558 -0
  98. package/dist/content/templates/pipeline.html +494 -0
  99. package/dist/content/templates/productbook.html +540 -0
  100. package/dist/content/templates/runbook.html +543 -0
  101. package/dist/content/templates/servicebook.html +523 -0
  102. package/dist/content-index.json +540 -0
  103. package/dist/docs/decisions/ADR-0001-minimalist-site-code.html +491 -0
  104. package/dist/docs/decisions/ADR-0002-ai-accessibility.html +434 -0
  105. package/dist/docs/decisions/ADR-0003-single-file-bundle.html +412 -0
  106. package/dist/docs/decisions/ADR-0004-bun-runtime.html +409 -0
  107. package/dist/docs/decisions/ADR-0005-plugin-contract-and-distribution.html +402 -0
  108. package/dist/docs/decisions/DDR-0001-viewport-locked-layout.html +459 -0
  109. package/dist/docs/decisions/DDR-0002-theme-system.html +452 -0
  110. package/dist/docs/decisions/DDR-0003-bounded-logo-slot.html +423 -0
  111. package/dist/docs/decisions/DDR-0004-slides-rendering-model.html +399 -0
  112. package/dist/docs/decisions/DDR-0005-deterministic-layout-boundary.html +422 -0
  113. package/dist/docs/decisions/index.html +11 -0
  114. package/dist/docs/userguide/cli/build.html +408 -0
  115. package/dist/docs/userguide/cli/bundle.html +419 -0
  116. package/dist/docs/userguide/cli/dev.html +428 -0
  117. package/dist/docs/userguide/cli/index.html +11 -0
  118. package/dist/docs/userguide/cli/init.html +436 -0
  119. package/dist/docs/userguide/cli/servers.html +393 -0
  120. package/dist/docs/userguide/cli/stop.html +408 -0
  121. package/dist/docs/userguide/cli/update.html +406 -0
  122. package/dist/docs/userguide/cli/version.html +406 -0
  123. package/dist/docs/userguide/cli.html +386 -0
  124. package/dist/docs/userguide/index.html +11 -0
  125. package/dist/docs/userguide/sharing.html +465 -0
  126. package/dist/index.html +387 -0
  127. package/dist/llms.txt +18 -0
  128. package/dist/provenance.json +7 -0
  129. package/dist/schemas/index.html +11 -0
  130. package/dist/schemas/plugin-registry.schema.html +327 -0
  131. package/dist/schemas/plugin-schemas-notes.html +364 -0
  132. package/dist/schemas/plugin.schema.html +327 -0
  133. package/dist/schemas/plugins.schema.html +327 -0
  134. package/dist/schemas/v0/common.schema.html +386 -0
  135. package/dist/schemas/v0/index.html +11 -0
  136. package/dist/schemas/v0/plugin-registry.schema.html +547 -0
  137. package/dist/schemas/v0/plugin.schema.html +497 -0
  138. package/dist/schemas/v0/plugins.schema.html +406 -0
  139. package/dist/schemas/v0/site.schema.html +541 -0
  140. package/dist/schemas/v0/theme.schema.html +615 -0
  141. package/dist/schemas.html +351 -0
  142. package/dist/styles.css +1262 -0
  143. package/package.json +4 -2
  144. package/plugins-dist/callouts.css +32 -0
  145. package/plugins-dist/callouts.js +46 -0
  146. package/plugins-dist/slides-visuals.css +224 -0
  147. package/plugins-dist/slides-visuals.js +598 -0
  148. package/registry/plugins.yaml +35 -0
  149. package/schemas/README.md +10 -0
  150. package/schemas/plugin-registry.schema.json +5 -0
  151. package/schemas/plugin-schemas-notes.md +71 -0
  152. package/schemas/plugin.schema.json +5 -0
  153. package/schemas/plugins.schema.json +5 -0
  154. package/schemas/v0/common.schema.json +64 -0
  155. package/schemas/v0/plugin-registry.schema.json +225 -0
  156. package/schemas/v0/plugin.schema.json +175 -0
  157. package/schemas/v0/plugins.schema.json +84 -0
  158. package/schemas/v0/site.schema.json +56 -9
  159. package/schemas/v0/theme.schema.json +105 -22
  160. package/scripts/build.ts +155 -3
  161. package/scripts/bundle.ts +258 -95
  162. package/scripts/dev.ts +203 -1
  163. package/src/__tests__/build.test.ts +158 -1
  164. package/src/__tests__/bundle.test.ts +31 -0
  165. package/src/__tests__/cli.test.ts +14 -3
  166. package/src/__tests__/fixtures/fences/slides-visuals/invalid/bad-list-indent.md +5 -0
  167. package/src/__tests__/fixtures/fences/slides-visuals/invalid/blank-line.md +5 -0
  168. package/src/__tests__/fixtures/fences/slides-visuals/invalid/compare-object-items.md +9 -0
  169. package/src/__tests__/fixtures/fences/slides-visuals/invalid/indented-fence.md +4 -0
  170. package/src/__tests__/fixtures/fences/slides-visuals/invalid/stat-grid-missing-fields.md +5 -0
  171. package/src/__tests__/fixtures/fences/slides-visuals/invalid/unknown-type.md +3 -0
  172. package/src/__tests__/fixtures/fences/slides-visuals/valid/compare.md +10 -0
  173. package/src/__tests__/fixtures/fences/slides-visuals/valid/comparison-table.md +14 -0
  174. package/src/__tests__/fixtures/fences/slides-visuals/valid/funnel.md +7 -0
  175. package/src/__tests__/fixtures/fences/slides-visuals/valid/kpi.md +5 -0
  176. package/src/__tests__/fixtures/fences/slides-visuals/valid/layer-cake.md +6 -0
  177. package/src/__tests__/fixtures/fences/slides-visuals/valid/pyramid.md +6 -0
  178. package/src/__tests__/fixtures/fences/slides-visuals/valid/quadrant-grid.md +8 -0
  179. package/src/__tests__/fixtures/fences/slides-visuals/valid/scorecard.md +13 -0
  180. package/src/__tests__/fixtures/fences/slides-visuals/valid/stat-grid.md +8 -0
  181. package/src/__tests__/init.test.ts +35 -0
  182. package/src/__tests__/plugin-loader.test.ts +221 -0
  183. package/src/__tests__/shared.test.ts +428 -0
  184. package/src/__tests__/slides-visuals-fence-contract.test.ts +28 -0
  185. package/src/__tests__/slides-visuals-runtime-regressions.bun.test.ts +114 -0
  186. package/src/__tests__/styles.test.ts +35 -0
  187. package/src/cli.ts +9 -4
  188. package/src/plugin-loader.ts +245 -0
  189. package/src/shared.ts +614 -7
  190. package/src/site/styles.css +331 -0
  191. package/src/site/template.html +66 -5
  192. package/src/templates/deck.ts +186 -0
  193. package/src/templates/driver.ts +11 -1
  194. package/src/templates/minimal.ts +1 -0
package/dist/content/reference/design-catalog.html ADDED
@@ -0,0 +1,449 @@
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>Design Catalog (Shapes and Figures) - 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.0</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" class="active">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/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>design-catalog</span></nav>
139
+ <div class="page-meta">Last updated: 2026-02-12</div>
140
+ <h1 id="design-catalog-shapes-and-figures">Design Catalog (Shapes and Figures)</h1>
141
+ <p>Kitfly is <strong>not</strong> trying to recreate diagram engines like Mermaid or PlantUML.</p>
142
+ <p>Those tools compute layout from relationships (a graph). That’s powerful, but the output can be hard to predict and hard for AI agents to control precisely.</p>
143
+ <p>Kitfly’s approach is simpler: a small catalog of <strong>deterministic</strong> building blocks that render predictably inside a slide.</p>
144
+ <h2 id="the-two-layers">The two layers</h2>
145
+ <h3 id="shapes-primitives">Shapes (primitives)</h3>
146
+ <p><strong>Shapes</strong> are atomic building blocks with <strong>no internal layout logic</strong>.</p>
147
+ <p>They are the “ink” you can draw with:</p>
148
+ <ul>
149
+ <li>boxes, circles, diamonds</li>
150
+ <li>arrows and connectors</li>
151
+ <li>badges, labels, callouts</li>
152
+ </ul>
153
+ <p>You (or an agent) decide where they go.</p>
154
+ <h3 id="figures-deterministic-infographic-patterns">Figures (deterministic infographic patterns)</h3>
155
+ <p><strong>Figures</strong> are composed patterns built from shapes.</p>
156
+ <p>A figure has a known structure (a fixed topology) and a deterministic layout algorithm, such as CSS Grid or flexbox. You fill named <strong>slots</strong>, and the figure handles spacing and alignment inside its bounding box.</p>
157
+ <p>Examples of figures we expect to support:</p>
158
+ <ul>
159
+ <li>timeline</li>
160
+ <li>layer cake</li>
161
+ <li>quadrant grid</li>
162
+ <li>hub-and-spoke</li>
163
+ <li>funnel</li>
164
+ <li>cycle wheel</li>
165
+ </ul>
166
+ <h2 id="the-boundary-rule-simple">The boundary rule (simple)</h2>
167
+ <p>If you can enumerate the elements and assign them positions (or slots) at authoring time, it belongs in the <strong>shapes/figures</strong> system.</p>
168
+ <p>If element positions must be computed from relationships between a variable set of nodes, it belongs in a <strong>diagram engine</strong>.</p>
169
+ <h2 id="why-this-helps-especially-for-ai">Why this helps (especially for AI)</h2>
170
+ <ul>
171
+ <li><strong>Predictable output</strong>: “Put this in column 2” is easier than “hope the layout engine does what I meant”.</li>
172
+ <li><strong>Slide-quality control</strong>: common business infographics need alignment more than graph theory.</li>
173
+ <li><strong>Minimal surface area</strong>: a catalog is easier to learn and easier to audit than a full diagram framework.</li>
174
+ </ul>
175
+ <h2 id="where-this-is-going">Where this is going</h2>
176
+ <p>This page is the entry point. During the v0.2.x cycle, we’ll extend it with:</p>
177
+ <ul>
178
+ <li>a fuller shape list (what exists, what each is for)</li>
179
+ <li>a figure list (patterns, slot definitions, examples)</li>
180
+ <li>guidance on when to choose figures vs Mermaid (and when not to)</li>
181
+ </ul>
182
+ <h2 id="what-ships-now-current">What ships now (current)</h2>
183
+ <p>Current core support focuses on <strong>shapes</strong> as <code>.block</code> modifiers:</p>
184
+ <ul>
185
+ <li><code>circle</code></li>
186
+ <li><code>pill</code></li>
187
+ <li><code>diamond</code></li>
188
+ <li><code>chevron</code></li>
189
+ <li><code>hexagon</code></li>
190
+ <li><code>triangle</code></li>
191
+ <li><code>block-arrow</code></li>
192
+ </ul>
193
+ <p>For simple directional storytelling, use <code>block-flow</code> with directional shapes.<br>General connector routing remains deferred to plugin/engine phases.</p>
194
+ <h2 id="how-to-use-this-today">How to use this (today)</h2>
195
+ <p>These examples use plain HTML inside Markdown. That’s intentional: it’s simple, deterministic, and easy for both AI agents and frontend authors to write and review.</p>
196
+ <p>You can use these classes in slides mode (recommended) and in docs mode when you want a diagram-like block in the middle of a page.</p>
197
+ <h2 id="live-examples">Live Examples</h2>
198
+ <p>Use the theme toggle in the header to switch light/dark and see the same examples adapt automatically.</p>
199
+ <h3 id="shape-gallery-atomic-primitives">Shape gallery (atomic primitives)</h3>
200
+ <div class="block-grid cols-4">
201
+ <div class="block">box</div>
202
+ <div class="block circle accent">1</div>
203
+ <div class="block pill accent">pill</div>
204
+ <div class="block diamond">diamond</div>
205
+ <div class="block chevron">chevron</div>
206
+ <div class="block hexagon">hex</div>
207
+ <div class="block triangle">tri</div>
208
+ <div class="block block-arrow accent">arrow</div>
209
+ </div>
210
+
211
+ <pre><code class="language-html">&lt;div class=&quot;block-grid cols-4&quot;&gt;
212
+ &lt;div class=&quot;block&quot;&gt;box&lt;/div&gt;
213
+ &lt;div class=&quot;block circle accent&quot;&gt;1&lt;/div&gt;
214
+ &lt;div class=&quot;block pill accent&quot;&gt;pill&lt;/div&gt;
215
+ &lt;div class=&quot;block diamond&quot;&gt;diamond&lt;/div&gt;
216
+ &lt;div class=&quot;block chevron&quot;&gt;chevron&lt;/div&gt;
217
+ &lt;div class=&quot;block hexagon&quot;&gt;hex&lt;/div&gt;
218
+ &lt;div class=&quot;block triangle&quot;&gt;tri&lt;/div&gt;
219
+ &lt;div class=&quot;block block-arrow accent&quot;&gt;arrow&lt;/div&gt;
220
+ &lt;/div&gt;
221
+ </code></pre>
222
+ <h3 id="directional-flow-no-connector-engine">Directional flow (no connector engine)</h3>
223
+ <div class="block-flow">
224
+ <div class="block chevron">Intake</div>
225
+ <div class="block block-arrow accent">Assess</div>
226
+ <div class="block chevron">Plan</div>
227
+ <div class="block block-arrow accent">Ship</div>
228
+ </div>
229
+
230
+ <pre><code class="language-html">&lt;div class=&quot;block-flow&quot;&gt;
231
+ &lt;div class=&quot;block chevron&quot;&gt;Intake&lt;/div&gt;
232
+ &lt;div class=&quot;block block-arrow accent&quot;&gt;Assess&lt;/div&gt;
233
+ &lt;div class=&quot;block chevron&quot;&gt;Plan&lt;/div&gt;
234
+ &lt;div class=&quot;block block-arrow accent&quot;&gt;Ship&lt;/div&gt;
235
+ &lt;/div&gt;
236
+ </code></pre>
237
+ <h3 id="modifier-comparison-same-base-shape-side-by-side">Modifier comparison (same base shape, side-by-side)</h3>
238
+ <div class="block-grid cols-4">
239
+ <div class="block">default</div>
240
+ <div class="block accent">accent</div>
241
+ <div class="block outline">outline</div>
242
+ <div class="block muted">muted</div>
243
+ </div>
244
+
245
+ <pre><code class="language-html">&lt;div class=&quot;block-grid cols-4&quot;&gt;
246
+ &lt;div class=&quot;block&quot;&gt;default&lt;/div&gt;
247
+ &lt;div class=&quot;block accent&quot;&gt;accent&lt;/div&gt;
248
+ &lt;div class=&quot;block outline&quot;&gt;outline&lt;/div&gt;
249
+ &lt;div class=&quot;block muted&quot;&gt;muted&lt;/div&gt;
250
+ &lt;/div&gt;
251
+ </code></pre>
252
+ <h3 id="modifier-comparison-on-one-shape-circle">Modifier comparison on one shape (circle)</h3>
253
+ <div class="block-grid cols-4">
254
+ <div class="block circle">A</div>
255
+ <div class="block circle accent">A</div>
256
+ <div class="block circle outline">A</div>
257
+ <div class="block circle muted">A</div>
258
+ </div>
259
+
260
+ <pre><code class="language-html">&lt;div class=&quot;block-grid cols-4&quot;&gt;
261
+ &lt;div class=&quot;block circle&quot;&gt;A&lt;/div&gt;
262
+ &lt;div class=&quot;block circle accent&quot;&gt;A&lt;/div&gt;
263
+ &lt;div class=&quot;block circle outline&quot;&gt;A&lt;/div&gt;
264
+ &lt;div class=&quot;block circle muted&quot;&gt;A&lt;/div&gt;
265
+ &lt;/div&gt;
266
+ </code></pre>
267
+
268
+ </article>
269
+ <aside class="toc"><span class="toc-title">On this page</span><ul><li><a href="#the-two-layers">The two layers</a></li><li class="toc-h3"><a href="#shapes-primitives">Shapes (primitives)</a></li><li class="toc-h3"><a href="#figures-deterministic-infographic-patterns">Figures (deterministic infographic patterns)</a></li><li><a href="#the-boundary-rule-simple">The boundary rule (simple)</a></li><li><a href="#why-this-helps-especially-for-ai">Why this helps (especially for AI)</a></li><li><a href="#where-this-is-going">Where this is going</a></li><li><a href="#what-ships-now-current">What ships now (current)</a></li><li><a href="#how-to-use-this-today">How to use this (today)</a></li><li><a href="#live-examples">Live Examples</a></li><li class="toc-h3"><a href="#shape-gallery-atomic-primitives">Shape gallery (atomic primitives)</a></li><li class="toc-h3"><a href="#directional-flow-no-connector-engine">Directional flow (no connector engine)</a></li><li class="toc-h3"><a href="#modifier-comparison-same-base-shape-side-by-side">Modifier comparison (same base shape, side-by-side)</a></li><li class="toc-h3"><a href="#modifier-comparison-on-one-shape-circle">Modifier comparison on one shape (circle)</a></li></ul></aside>
270
+ </main>
271
+ </div>
272
+
273
+ <footer class="site-footer">
274
+ <div class="footer-content">
275
+ <div class="footer-left">
276
+ <span class="footer-version">v0.2.0</span>
277
+ <span class="footer-separator">·</span>
278
+ <span class="footer-commit" title="Commit: 33ccd68">Published 2026-02-15</span>
279
+ </div>
280
+ <div class="footer-center">
281
+ <span class="footer-copyright"><a href="https://3leaps.net" class="footer-link">© 2026 3 Leaps, LLC</a></span>
282
+ <span class="footer-separator">·</span><a href="/" class="footer-link">Kitfly</a>
283
+ </div>
284
+ <div class="footer-right">
285
+ <a href="https://kitfly.dev" class="footer-link">Built with Kitfly</a>
286
+ </div>
287
+ </div>
288
+ </footer>
289
+ <!-- Syntax highlighting - Prism.js -->
290
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js"></script>
291
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/plugins/autoloader/prism-autoloader.min.js"></script>
292
+ <!-- Mermaid diagram support -->
293
+ <script type="module">
294
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
295
+
296
+ function getMermaidTheme() {
297
+ const theme = document.documentElement.getAttribute('data-theme');
298
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
299
+ const isDark = theme === 'dark' || (!theme && prefersDark);
300
+ return isDark ? 'dark' : 'neutral';
301
+ }
302
+
303
+ mermaid.initialize({
304
+ startOnLoad: true,
305
+ theme: getMermaidTheme()
306
+ });
307
+
308
+ // Re-render mermaid diagrams when theme changes
309
+ window.reinitMermaid = async function() {
310
+ mermaid.initialize({ startOnLoad: false, theme: getMermaidTheme() });
311
+ const diagrams = document.querySelectorAll('.mermaid');
312
+ for (const el of diagrams) {
313
+ const code = el.getAttribute('data-mermaid-source');
314
+ if (code) {
315
+ el.innerHTML = code;
316
+ el.removeAttribute('data-processed');
317
+ }
318
+ }
319
+ await mermaid.run({ nodes: diagrams });
320
+ };
321
+ </script>
322
+
323
+ <script>
324
+ function toggleTheme() {
325
+ const html = document.documentElement;
326
+ const current = html.getAttribute('data-theme');
327
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
328
+
329
+ let next;
330
+ if (current === 'dark') {
331
+ next = 'light';
332
+ } else if (current === 'light') {
333
+ next = 'dark';
334
+ } else {
335
+ // No explicit theme set, toggle from system preference
336
+ next = prefersDark ? 'light' : 'dark';
337
+ }
338
+
339
+ html.setAttribute('data-theme', next);
340
+ localStorage.setItem('theme', next);
341
+
342
+ // Switch Prism theme
343
+ const prismLight = document.getElementById('prism-light');
344
+ const prismDark = document.getElementById('prism-dark');
345
+ if (next === 'dark') {
346
+ prismLight?.setAttribute('disabled', '');
347
+ prismDark?.removeAttribute('disabled');
348
+ } else {
349
+ prismLight?.removeAttribute('disabled');
350
+ prismDark?.setAttribute('disabled', '');
351
+ }
352
+
353
+ // Re-render mermaid diagrams with new theme
354
+ if (window.reinitMermaid) {
355
+ window.reinitMermaid();
356
+ }
357
+ }
358
+
359
+ // Slides mode hash routing
360
+ (function initSlidesMode() {
361
+ const shell = document.querySelector('.slides-shell');
362
+ if (!shell) return;
363
+
364
+ const slides = Array.from(document.querySelectorAll('.slide'));
365
+ if (!slides.length) return;
366
+
367
+ const prevBtn = document.querySelector('.slide-prev');
368
+ const nextBtn = document.querySelector('.slide-next');
369
+ const counter = document.querySelector('.slide-counter');
370
+ const progressBar = document.querySelector('.slide-progress-bar');
371
+ const navLinks = Array.from(document.querySelectorAll('.sidebar-nav a[href^="#slide-"]'));
372
+ let current = 0;
373
+
374
+ function setActive(n) {
375
+ current = Math.max(0, Math.min(n, slides.length - 1));
376
+ slides.forEach((slide, idx) => slide.classList.toggle('active', idx === current));
377
+ navLinks.forEach((link) => {
378
+ const active = link.getAttribute('href') === '#' + slides[current].id;
379
+ link.classList.toggle('active', active);
380
+ });
381
+ if (counter) counter.textContent = (current + 1) + ' / ' + slides.length;
382
+ if (progressBar) progressBar.style.width = (((current + 1) / slides.length) * 100) + '%';
383
+ if (prevBtn) prevBtn.disabled = current === 0;
384
+ if (nextBtn) nextBtn.disabled = current === slides.length - 1;
385
+ history.replaceState(null, '', '#' + slides[current].id);
386
+ }
387
+
388
+ function setFromHash() {
389
+ const hash = window.location.hash || '';
390
+ const idx = slides.findIndex((s) => '#' + s.id === hash);
391
+ if (idx >= 0) setActive(idx);
392
+ else setActive(0);
393
+ }
394
+
395
+ prevBtn?.addEventListener('click', () => setActive(current - 1));
396
+ nextBtn?.addEventListener('click', () => setActive(current + 1));
397
+
398
+ document.addEventListener('keydown', (e) => {
399
+ if (e.key === 'ArrowRight' || e.key === ' ') {
400
+ e.preventDefault();
401
+ setActive(current + 1);
402
+ } else if (e.key === 'ArrowLeft') {
403
+ e.preventDefault();
404
+ setActive(current - 1);
405
+ } else if (e.key === 'Home') {
406
+ e.preventDefault();
407
+ setActive(0);
408
+ } else if (e.key === 'End') {
409
+ e.preventDefault();
410
+ setActive(slides.length - 1);
411
+ }
412
+ });
413
+
414
+ window.addEventListener('hashchange', setFromHash);
415
+ setFromHash();
416
+ })();
417
+
418
+ // Copy code button
419
+ document.querySelectorAll('.prose pre code').forEach(block => {
420
+ const button = document.createElement('button');
421
+ button.className = 'copy-button';
422
+ button.textContent = 'Copy';
423
+ button.onclick = async () => {
424
+ await navigator.clipboard.writeText(block.textContent);
425
+ button.textContent = 'Copied!';
426
+ setTimeout(() => button.textContent = 'Copy', 2000);
427
+ };
428
+ block.parentElement.appendChild(button);
429
+ });
430
+
431
+ // Mobile nav toggle
432
+ function toggleNav() {
433
+ document.querySelector('.sidebar').classList.toggle('open');
434
+ }
435
+
436
+ // Close nav when clicking outside on mobile
437
+ document.addEventListener('click', (e) => {
438
+ const sidebar = document.querySelector('.sidebar');
439
+ const toggle = document.querySelector('.nav-toggle');
440
+ if (sidebar.classList.contains('open') &&
441
+ !sidebar.contains(e.target) &&
442
+ !toggle.contains(e.target)) {
443
+ sidebar.classList.remove('open');
444
+ }
445
+ });
446
+ </script>
447
+
448
+ </body>
449
+ </html>