mdx-artifacts 0.1.2 → 0.2.0

package/artifact-docs/examples/decision-matrix.mdx

@@ -1,62 +1,134 @@
-import { DecisionMatrix, ExportPanel, OptionGrid } from "mdx-artifacts/react";
+import { ContentSet, ExportPanel, SortableList } from "mdx-artifacts/react";
 
-# Artifact Kit Stage One Decision
+# MDX Artifacts Stage One Content Set
 
-<DecisionMatrix
-  id="decision.stage-one"
-  question="Should stage one focus on a **Vite single HTML artifact** instead of starting with an Astro docs site?"
-  options={[
-    {
-      id: "vite",
-      name: "**Vite** single HTML artifact",
-      summary: "Validate the shortest `MDX -> HTML` loop first.",
-      pros: ["Shortest loop", "Direct interactive component debugging", "Fits one-off tool artifacts"],
-      cons: ["No docs-site navigation yet", "Weaker long-term archive experience"],
-      confidence: "high",
-      verdict: "Recommended for stage one"
-    },
-    {
-      id: "astro",
-      name: "Astro docs site",
-      summary: "Turn the artifact-docs tree into a structured static docs site.",
-      pros: ["Better long-term reading experience", "File-based pages", "Good for archives"],
-      cons: ["Too heavy for stage one", "Mixes component protocol work with docs-site engineering"],
-      confidence: "medium",
-      verdict: "Add in stage two"
-    },
-    {
-      id: "raw-html",
-      name: "Raw HTML",
-      summary: "Let agents generate complete HTML directly.",
-      pros: ["No toolchain", "Fast for very small throwaway pages"],
-      cons: ["Duplicated code", "Style drift", "~~Reusable~~ export behavior is hard to reuse"],
-      confidence: "low",
-      verdict: "Keep only as fallback"
-    }
-  ]}
-/>
+<ContentSet
+  id="set.stage-one"
+  title="Should stage one focus on a **Vite single HTML artifact** instead of starting with an Astro docs site?"
+  icon="🧭"
+  layout="grid"
+  columns={3}
+  surface="subtle"
+>
+  <ContentSet.Item
+    id="vite"
+    title="**Vite** single HTML artifact"
+    badge="Recommended"
+    icon="✅"
+    tone="positive"
+    emphasis="primary"
+    summary="Validate the shortest `MDX -> HTML` loop first."
+  >
+    ### Tradeoffs
 
-<OptionGrid
-  id="option.first-components"
+    - Shortest loop
+    - Direct interactive component debugging
+    - Fits one-off tool artifacts
+    - No docs-site navigation yet
+    - Weaker long-term archive experience
+  </ContentSet.Item>
+  <ContentSet.Item
+    id="astro"
+    title="Astro docs site"
+    badge="Later"
+    icon="🗂️"
+    tone="info"
+    summary="Turn the artifact-docs tree into a structured static docs site."
+  >
+    ### Tradeoffs
+
+    - Better long-term reading experience
+    - File-based pages
+    - Good for archives
+    - Too heavy for stage one
+    - Mixes component protocol work with docs-site engineering
+  </ContentSet.Item>
+  <ContentSet.Item
+    id="raw-html"
+    title="Raw HTML"
+    badge="Fallback"
+    icon="⚠️"
+    tone="warning"
+    emphasis="subtle"
+    summary="Let agents generate complete HTML directly."
+  >
+    ### Tradeoffs
+
+    - No toolchain
+    - Fast for very small throwaway pages
+    - Duplicated code
+    - Style drift
+    - ~~Reusable~~ export behavior is hard to reuse
+  </ContentSet.Item>
+</ContentSet>
+
+<ContentSet
+  id="set.first-components"
   title="First component scope"
-  options={[
+  layout="grid"
+  columns={3}
+>
+  <ContentSet.Item
+    id="content-set"
+    title="ContentSet"
+    badge="Core"
+    tone="accent"
+    emphasis="primary"
+    summary="Group reusable content items."
+  >
+    Use for comparable options, recommendations, risks, and findings.
+
+    - Stable item slots
+    - Tone and emphasis styling
+  </ContentSet.Item>
+  <ContentSet.Item
+    id="content-item"
+    title="ContentItem"
+    summary="Render a standalone content card."
+  >
+    Use when a single reusable content block is enough.
+
+    - Easy to scan
+    - Keeps Markdown body content readable
+  </ContentSet.Item>
+  <ContentSet.Item
+    id="export-panel"
+    title="ExportPanel"
+    tone="info"
+    summary="Return conclusions or edits to the workflow."
+  >
+    Use when the artifact needs to hand structured results back to the agent.
+
+    - Copy-only in v1
+    - Can add file download later
+  </ContentSet.Item>
+</ContentSet>
+
+<SortableList
+  id="list.next-priorities"
+  title="Next priorities"
+  summary="Drag items or use the controls to change the priority order."
+  items={[
     {
-      id: "decision-matrix",
-      name: "DecisionMatrix",
-      intent: "Compare options",
-      tradeoffs: ["Stable **decision** structure", "Does not own complex interaction"]
+      id: "validate-build",
+      title: "Keep validate/build/dev reliable",
+      summary: "The CLI loop is the artifact authoring baseline.",
+      badge: "P0",
+      tags: ["cli"]
     },
     {
-      id: "option-grid",
-      name: "OptionGrid",
-      intent: "Show alternatives side by side",
-      tradeoffs: ["Easy to scan", "Can add selection later"]
+      id: "example-output",
+      title: "Verify example HTML output",
+      summary: "The example MDX must keep producing standalone HTML.",
+      badge: "P1",
+      tags: ["artifact"]
     },
     {
-      id: "export-panel",
-      name: "ExportPanel",
-      intent: "Return conclusions or edits to the workflow",
-      tradeoffs: ["Copy-only in v1", "Can add file download later"]
+      id: "adapter-design",
+      title: "Design the Astro adapter later",
+      summary: "Adapter work should follow the component protocol.",
+      badge: "Later",
+      tags: ["adapter"]
     }
   ]}
 />

package/artifact-docs/examples/layout-composition.mdx

@@ -1,14 +1,14 @@
 import {
   Columns,
   ComparisonSet,
-  DecisionMatrix,
+  ContentSet,
   ExportPanel,
   Frame,
   Grid,
   InlineText,
   MarkdownBody,
   SplitPane,
-  Stack,
+  Stack
 } from "mdx-artifacts/react";
 
 # Layout Composition Example
@@ -16,177 +16,155 @@ import {
 <Stack gap="lg">
   <Frame surface="plain" padding="lg">
     <Stack gap="sm">
-      <InlineText
-        as="h2"
-        variant="title"
-        text="A composed artifact using **layout primitives** and text components"
-      />
-      <MarkdownBody
-        body={`This example shows how \`Stack\`, \`Columns\`, \`Grid\`, \`SplitPane\`, and \`Frame\` can arrange existing semantic components without replacing them.
-
-The layout components control placement and surface. Components such as \`DecisionMatrix\`, \`ComparisonSet\`, and \`ExportPanel\` still own the artifact meaning.`}
-/>
-
-</Stack>
-
+      <InlineText as="h2" variant="title">
+        A composed artifact using **layout primitives** and text components
+      </InlineText>
+      <MarkdownBody>
+        {`This example shows how \`Stack\`, \`Columns\`, \`Grid\`, \`SplitPane\`, and \`Frame\` can arrange existing content components without replacing them.
+
+The layout components control placement and surface. Components such as \`ContentSet\`, \`ComparisonSet\`, and \`ExportPanel\` still own reusable content structure and handoff behavior.`}
+      </MarkdownBody>
+    </Stack>
   </Frame>
 
   <SplitPane ratio="3:1" gap="lg">
-    <DecisionMatrix
-      id="decision.layout-authoring"
-      question="Should layout primitives become the default authoring path?"
-      options={[
-        {
-          id: "semantic-first",
-          name: "Semantic-first authoring",
-          summary: "Agents choose task-oriented components first, then use layout only when composition needs it.",
-          pros: ["Stable protocol", "Less ad hoc JSX", "Better validation path"],
-          cons: ["Less free-form than raw HTML"],
-          confidence: "high",
-          verdict: "Recommended"
-        },
-        {
-          id: "layout-first",
-          name: "Layout-first authoring",
-          summary: "Agents assemble artifacts from generic layout blocks and arbitrary children.",
-          pros: ["Maximum flexibility"],
-          cons: ["Easy to recreate raw HTML", "Harder to query through CLI", "Harder to keep consistent"],
-          confidence: "low",
-          verdict: "Keep as an advanced escape hatch"
-        }
-      ]}
-    />
+    <ContentSet
+      id="set.layout-authoring"
+      title="Should layout primitives become the default authoring path?"
+      layout="grid"
+      columns={2}
+    >
+      <ContentSet.Item
+        id="semantic-first"
+        title="Semantic-first authoring"
+        badge="Recommended"
+        tone="positive"
+        emphasis="primary"
+        summary="Agents choose task-oriented components first, then use layout only when composition needs it."
+      >
+        - Stable protocol
+        - Less ad hoc JSX
+        - Better validation path
+        - Less free-form than raw HTML
+      </ContentSet.Item>
+      <ContentSet.Item
+        id="layout-first"
+        title="Layout-first authoring"
+        badge="Advanced"
+        tone="warning"
+        emphasis="subtle"
+        summary="Agents assemble artifacts from generic layout blocks and arbitrary children."
+      >
+        - Maximum flexibility
+        - Easy to recreate raw HTML
+        - Harder to query through CLI
+        - Harder to keep consistent
+      </ContentSet.Item>
+    </ContentSet>
 
     <Frame surface="subtle">
       <Stack gap="sm">
-        <InlineText as="h3" variant="subtitle" text="Reading note" />
-        <MarkdownBody
-          variant="compact"
-          body={`Use layout primitives when the artifact needs a custom reading shape:
+        <InlineText as="h3" variant="subtitle">Reading note</InlineText>
+        <MarkdownBody variant="compact">
+          {`Use layout primitives when the artifact needs a custom reading shape:
 
 - main content plus sidebar
 - equal option previews
 - framed snippets or mockups
 
 Do not use them to rebuild existing semantic components.`}
-/>
-
-</Stack>
-</Frame>
-
+        </MarkdownBody>
+      </Stack>
+    </Frame>
   </SplitPane>
 
   <Columns ratio="1:1:1" gap="md">
     <Frame surface="outlined">
-      <InlineText as="h3" variant="subtitle" text="InlineText" />
-      <MarkdownBody
-        variant="compact"
-        body={`Short labels and headings can use **inline Markdown**, including *emphasis*, ~~removed text~~, and \`inline code\`.`}
-      />
+      <InlineText as="h3" variant="subtitle">InlineText</InlineText>
+      <MarkdownBody variant="compact">
+        Short labels and headings can use **inline Markdown**, including *emphasis*, ~~removed text~~, and `inline code`.
+      </MarkdownBody>
     </Frame>
 
     <Frame surface="outlined">
-      <InlineText as="h3" variant="subtitle" text="MarkdownBody" />
-      <MarkdownBody
-        variant="compact"
-        body={`Body copy supports controlled Markdown:
+      <InlineText as="h3" variant="subtitle">MarkdownBody</InlineText>
+      <MarkdownBody variant="compact">
+        {`Body copy supports controlled Markdown:
 
 1.  paragraphs
 2.  ordered lists
 3.  unordered lists
 4.  blockquotes`}
-    />
-
-                  </Frame>
-
-                  <Frame surface="outlined">
-
-              <InlineText as="h3" variant="subtitle" text="Frame" />
-
-          <MarkdownBody
+      </MarkdownBody>
+    </Frame>
 
-    variant="compact"
-    body={`Frame provides surface treatment:
+    <Frame surface="outlined">
+      <InlineText as="h3" variant="subtitle">Frame</InlineText>
+      <MarkdownBody variant="compact">
+        {`Frame provides surface treatment:
 
 - \`none\`
 - \`plain\`
 - \`subtle\`
 - \`outlined\``}
-  />
-
-                </Frame>
-
-            </Columns>
-
-              <ComparisonSet id="comparison.content-shapes" title="Compare content shapes" columns={3}>
-
-          <ComparisonSet.Item id="markdown-body" title="Markdown body" value="markdown-body">
-
-      <MarkdownBody
+      </MarkdownBody>
+    </Frame>
+  </Columns>
 
-  variant="compact"
-  body={`# This **item** is ~~plain Markdown content~~.
+  <ComparisonSet id="comparison.content-shapes" title="Compare content shapes" columns={3}>
+    <ComparisonSet.Item id="markdown-body" title="Markdown body" value="markdown-body">
+      <MarkdownBody variant="compact">
+        {`# This **item** is ~~plain Markdown content~~.
 
-  #### **item** is ~~plain Markdown content~~.
+#### **item** is ~~plain Markdown content~~.
 
 - Good for notes
 - Easy for agents to write
 - Easy to validate
 
 1. Ordered item
-2. Nested content check
-
-`}
-/>
-
-                  </ComparisonSet.Item>
-
-<ComparisonSet.Item id="framed-snippet" title="Framed snippet" value="framed-snippet">
-  <Frame surface="subtle">
-    <MarkdownBody
-      variant="compact"
-      body={`This slot can hold a future \`CodeBlock\`, \`MermaidBlock\`, image renderer, or project-local component.`}
-    />
-  </Frame>
-</ComparisonSet.Item>
-
-                  <ComparisonSet.Item id="custom-composition" title="Custom composition" value="custom-composition">
-                  <Stack gap="sm">
-                    <InlineText text="Nested layout is allowed when the item needs it." variant="label" />
-                    <MarkdownBody body="The comparison item owns the title. Its body remains open to child components." variant="compact" />
-                  </Stack>
-
-                </ComparisonSet.Item>
-
-            </ComparisonSet>
-
-                <Grid columns={2} gap="md">
-
-              <Frame surface="outlined">
-
-          <InlineText as="h3" variant="subtitle" text="Grid is only layout" />
-
-      <MarkdownBody
-
-body={`This card is built manually from \`Frame\`, \`InlineText\`, and \`MarkdownBody\`.
+2. Nested content check`}
+      </MarkdownBody>
+    </ComparisonSet.Item>
+
+    <ComparisonSet.Item id="framed-snippet" title="Framed snippet" value="framed-snippet">
+      <Frame surface="subtle">
+        <MarkdownBody variant="compact">
+          This slot can hold a future `CodeBlock`, `MermaidBlock`, image renderer, or project-local component.
+        </MarkdownBody>
+      </Frame>
+    </ComparisonSet.Item>
+
+    <ComparisonSet.Item id="custom-composition" title="Custom composition" value="custom-composition">
+      <Stack gap="sm">
+        <InlineText variant="label">Nested layout is allowed when the item needs it.</InlineText>
+        <MarkdownBody variant="compact">
+          The comparison item owns the title. Its body remains open to child components.
+        </MarkdownBody>
+      </Stack>
+    </ComparisonSet.Item>
+  </ComparisonSet>
+
+  <Grid columns={2} gap="md">
+    <Frame surface="outlined">
+      <InlineText as="h3" variant="subtitle">Grid is only layout</InlineText>
+      <MarkdownBody>
+        {`This card is built manually from \`Frame\`, \`InlineText\`, and \`MarkdownBody\`.
 
 Use this when there is no reusable artifact meaning beyond placement.`}
-/>
-
-</Frame>
+      </MarkdownBody>
+    </Frame>
 
     <Frame surface="plain" padding="lg">
       <Stack gap="md">
-        <InlineText as="h3" variant="subtitle" text="Surface check" />
-        <MarkdownBody
-          body={`This frame uses \`surface=\"plain\"\`. In light mode it should read as a white surface on a very light neutral page background.
+        <InlineText as="h3" variant="subtitle">Surface check</InlineText>
+        <MarkdownBody>
+          {`This frame uses \`surface="plain"\`. In light mode it should read as a white surface on a very light neutral page background.
 
 In dark mode it should read as a quiet elevated surface, not as a blue-tinted panel.`}
-/>
-
-</Stack>
-</Frame>
-
+        </MarkdownBody>
+      </Stack>
+    </Frame>
   </Grid>
 
   <ExportPanel