concept-atlas-dense-explain 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concept-atlas-dense-explain",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Portable dense-explanation skill and MDX concept atlas template",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -9,17 +9,21 @@ Use the `concept-atlas-dense-explain` npm CLI. This skill is intentionally light
 
 ## Workflow
 
-1. Choose the carrier before writing any MDX. A (continuous reading) uses a document-flow MDX structure; B (interactive Concept Atlas) uses a concept-graph MDX structure. Recommend B when the reader needs concept navigation or a relation graph; recommend A for a conventional HTML reading flow with denser horizontal component grids.
+1. Choose the page shell before writing MDX. `atlas` uses a concept graph with node navigation; `scroll` uses a continuous document flow. The component library is shared: information-density components such as `Insight`, `Flow`, `FrameworkModel`, `MatrixModel`, `Mermaid`, `RelationMap`, `NoteGrid`, `Callout`, `Details`, `Columns`, `Grid`, `Stack`, and `Tabs` can be used wherever their meaning fits. Recommend `atlas` when the reader needs concept navigation or a relation graph; recommend `scroll` for a conventional reading flow.
 2. When a starting point is useful, create a single MDX file with `npx concept-atlas-dense-explain create <file>.mdx --mode atlas|scroll`, then rewrite it with the AI.
 3. For B, write semantic MDX to the user-selected `.mdx` file. Include one `L0`, multiple `L1` branches, useful depth, `Children`/`ConceptRef`, and labeled `Relation`s. This content renders through the interactive atlas entry.
-4. For A, write semantic MDX to the user-selected `.mdx` file with `ScrollDocument`, `ScrollHeader`, `ScrollSection`, `ScrollProse`, and `ScrollGrid`. Do not wrap it in `ExplainPage`, `ConceptGraph`, or `ConceptNode`. This content renders through the continuous-reader entry.
-5. Do not try to make one MDX file serve both carriers. The template ships both sample entries for reference, but they represent distinct authoring formats.
-6. Compile directly with `npx concept-atlas-dense-explain <file>.mdx --mode atlas|scroll`. The output is a standalone `.html` beside the MDX unless `-o` is provided. The mode can be detected from the top-level carrier, but specify it when the file is ambiguous.
-7. Report the selected mode, output path, and limitations. Do not claim interactions that were not verified.
+4. For `scroll`, use `ScrollDocument`, `ScrollHeader`, `ScrollSection`, `ScrollProse`, and `ScrollGrid` as the document shell. Put shared information components inside sections as needed.
+5. For `atlas`, use `ExplainPage`, `ConceptGraph`, `ConceptNode`, `Children`, `ConceptRef`, and `Relation` as the graph shell. Put shared information components inside nodes as needed.
+6. Do not force one MDX file to be both page shells. This is a shell distinction, not a component-library distinction; convert only the outer structure when changing carriers.
+7. Compile directly with `npx concept-atlas-dense-explain <file>.mdx --mode atlas|scroll`. The output is a standalone `.html` beside the MDX unless `-o` is provided. The mode can be detected from the top-level carrier, but specify it when the file is ambiguous.
+8. Report the selected mode, output path, and limitations. Do not claim interactions that were not verified.
 
 ## Content rules
 
 - Keep MDX semantic; do not write CSS, coordinates, SVG, or replacement application code.
 - Give important nodes a claim-like title, a one-sentence summary, evidence, and meaningful components.
-- Use only components and relation types supported by the built-in renderer.
+- Treat the built-in component library as shared across carriers; choose components by the relationship they express, not by the page shell.
+- Keep the outer shell valid for the selected carrier and keep component props valid; the renderer does not convert arbitrary JSX or CSS into a semantic component automatically.
+- For array props, use the documented object shapes: `Flow.steps` accepts strings or `{ title, description }`, `Timeline.events` uses `{ label, content }`, table rows use `string[][]`, and model data uses arrays of named objects.
+- For continuous reading, configure spacing on the shell with `ScrollDocument spacing="compact|comfortable|airy"`; use `ScrollSection spacing="..."` only for a local override instead of adding manual margins.
 - If the CLI or npm registry is unavailable, report the blocker instead of copying the implementation into the skill.

package/template/src/components/MDXComponents.jsx

@@ -194,16 +194,16 @@ export function DecisionMatrix({ title = '权衡矩阵', headers = [], rows = []
 }
 DecisionMatrix.displayName = 'DecisionMatrix';
 
-export function Flow({ steps = [], children }) {
-  if (steps.length > 0) {
-    return (
-      <div className="semantic-flow-steps">
-        {steps.map((step, idx) => (
-          <div key={idx} className="flow-step">
-            <span className="step-num">{idx + 1}</span>
-            <span className="step-text">{step}</span>
-            {idx < steps.length - 1 && <span className="step-arrow">→</span>}
-          </div>
+export function Flow({ steps = [], children }) {
+  if (steps.length > 0) {
+    return (
+      <div className="semantic-flow-steps">
+        {steps.map((step, idx) => (
+          <div key={idx} className="flow-step">
+            <span className="step-num">{idx + 1}</span>
+            <span className="step-text">{typeof step === 'object' ? <><strong>{step.title || step.label || `步骤 ${idx + 1}`}</strong>{step.description && <small>{step.description}</small>}</> : step}</span>
+            {idx < steps.length - 1 && <span className="step-arrow">→</span>}
+          </div>
         ))}
       </div>
     );
@@ -357,8 +357,9 @@ export function Columns({ children }) {
 }
 Columns.displayName = 'Columns';
 
-export function ScrollDocument({ children }) {
-  return <article className="continuous-document">{children}</article>;
+export function ScrollDocument({ spacing = 'comfortable', children }) {
+  const safeSpacing = ['compact', 'comfortable', 'airy'].includes(spacing) ? spacing : 'comfortable';
+  return <article className={`continuous-document continuous-spacing-${safeSpacing}`}>{children}</article>;
 }
 ScrollDocument.displayName = 'ScrollDocument';
 
@@ -367,9 +368,10 @@ export function ScrollHeader({ label = '连续阅读', title, children }) {
 }
 ScrollHeader.displayName = 'ScrollHeader';
 
-export function ScrollSection({ title, wide = false, children }) {
+export function ScrollSection({ title, wide = false, spacing = 'inherit', children }) {
+  const safeSpacing = ['compact', 'comfortable', 'airy'].includes(spacing) ? ` continuous-spacing-${spacing}` : '';
   return (
-    <section className={`continuous-section${wide ? ' continuous-section-wide' : ''}`}>
+    <section className={`continuous-section${wide ? ' continuous-section-wide' : ''}${safeSpacing}`}>
       {title && <h2>{title}</h2>}
       {children}
     </section>

package/template/src/styles/concept-explain.css

@@ -2890,10 +2890,10 @@ button.flow-box {
   --annotation-accent: var(--text-accent);
   margin: 14px 0;
   padding: 10px 0 10px 14px;
-  border: 0;
+  border: 1px solid var(--border-subtle);
   border-inline-start: 2px solid var(--annotation-accent);
-  border-radius: 0;
-  background: transparent;
+  border-radius: var(--radius-2);
+  background: var(--bg-surface);
   box-shadow: none;
 }
 
@@ -2986,8 +2986,14 @@ html[data-carrier='scroll'] #root {
 .continuous-document {
   width: min(1120px, 100%);
   margin: 0 auto;
+  --scroll-block-gap: 18px;
+  --scroll-grid-gap: 16px;
 }
 
+.continuous-spacing-compact { --scroll-block-gap: 10px; --scroll-grid-gap: 10px; }
+.continuous-spacing-comfortable { --scroll-block-gap: 18px; --scroll-grid-gap: 16px; }
+.continuous-spacing-airy { --scroll-block-gap: 28px; --scroll-grid-gap: 24px; }
+
 .continuous-header {
   max-width: 820px;
   margin: 0 0 56px;
@@ -3019,11 +3025,19 @@ html[data-carrier='scroll'] #root {
 }
 
 .continuous-section {
+  display: flex;
+  flex-direction: column;
+  gap: var(--scroll-block-gap);
   margin: 0 0 48px;
   padding: 0 0 48px;
   border-bottom: 1px solid var(--border-medium);
 }
 
+.continuous-section.continuous-spacing-compact { --scroll-block-gap: 10px; --scroll-grid-gap: 10px; }
+.continuous-section.continuous-spacing-comfortable { --scroll-block-gap: 18px; --scroll-grid-gap: 16px; }
+.continuous-section.continuous-spacing-airy { --scroll-block-gap: 28px; --scroll-grid-gap: 24px; }
+.continuous-section > * { margin-top: 0; margin-bottom: 0; }
+
 .continuous-section > h2,
 .continuous-model-pair h2 {
   margin: 0 0 14px;
@@ -3044,7 +3058,7 @@ html[data-carrier='scroll'] #root {
 
 .continuous-grid {
   display: grid;
-  gap: 16px;
+  gap: var(--scroll-grid-gap, 16px);
   align-items: stretch;
 }
 
@@ -3052,6 +3066,98 @@ html[data-carrier='scroll'] #root {
 .continuous-grid-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
 .continuous-grid-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }
 
+.semantic-flow-steps {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+  gap: 8px;
+  margin: 14px 0;
+  padding: 10px;
+  border: 1px solid var(--border-medium);
+  border-top: 2px solid var(--primary);
+  border-radius: var(--radius-3);
+  background: var(--bg-surface);
+}
+
+.flow-step {
+  position: relative;
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 8px;
+  align-items: start;
+  min-width: 0;
+  padding: 10px;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-2);
+  background: var(--bg-card);
+}
+
+.step-num {
+  display: grid;
+  place-items: center;
+  width: 22px;
+  height: 22px;
+  border-radius: 50%;
+  background: var(--bg-highlight);
+  color: var(--text-accent);
+  font: 700 11px/1 ui-monospace, monospace;
+}
+
+.step-text { color: var(--text-secondary); font-size: 12px; line-height: 1.45; }
+.step-text strong, .step-text small { display: block; }
+.step-text strong { color: var(--text-primary); font-size: 12px; }
+.step-text small { margin-top: 3px; color: var(--text-secondary); }
+.step-arrow { display: none; }
+
+.semantic-overview,
+.semantic-definition,
+.semantic-mechanism,
+.semantic-prerequisite,
+.semantic-input,
+.semantic-output,
+.semantic-glossary-item,
+.semantic-example,
+.semantic-boundary,
+.semantic-counterexample {
+  margin: 10px 0;
+  padding: 10px 12px;
+  border: 1px solid var(--border-medium);
+  border-radius: var(--radius-2);
+  background: var(--bg-surface);
+  color: var(--text-secondary);
+}
+
+.semantic-definition { border-top: 2px solid var(--border-strong); }
+.semantic-mechanism { background: color-mix(in srgb, var(--bg-surface) 82%, var(--bg-card)); }
+.semantic-example { background: var(--bg-card); box-shadow: inset 0 0 0 1px var(--border-subtle); }
+.semantic-boundary { border-style: dashed; }
+.semantic-counterexample { border-style: dotted; }
+.semantic-glossary-item { border-bottom-color: var(--border-strong); }
+
+.semantic-stack:has(> .semantic-definition, > .semantic-mechanism, > .semantic-boundary) {
+  margin: 14px 0;
+  padding: 10px 16px;
+  border: 1px solid var(--border-medium);
+  border-radius: var(--radius-3);
+  background: var(--bg-card);
+  box-shadow: 2px 3px 0 rgba(15, 23, 42, 0.12);
+}
+
+.semantic-stack:has(> .semantic-definition, > .semantic-mechanism, > .semantic-boundary) > .semantic-definition,
+.semantic-stack:has(> .semantic-definition, > .semantic-mechanism, > .semantic-boundary) > .semantic-mechanism,
+.semantic-stack:has(> .semantic-definition, > .semantic-mechanism, > .semantic-boundary) > .semantic-boundary {
+  margin: 0;
+  padding: 12px 0;
+  border: 0;
+  border-bottom: 1px solid var(--border-subtle);
+  border-radius: 0;
+  background: transparent;
+  box-shadow: none;
+}
+
+.semantic-stack:has(> .semantic-definition, > .semantic-mechanism, > .semantic-boundary) > :last-child {
+  border-bottom: 0;
+}
+
 .continuous-grid > .semantic-framework-model,
 .continuous-grid > .semantic-model-matrix,
 .continuous-grid > .semantic-model-formula,