Skip to content

Agent skills for useful HTML artifacts, wireframes, interactive prototypes, plans, and diagrams.

Add focused Frontend Slides reference (#15)

Michael Ramosfcc90244e883
diff --git a/components/catalog-explorer.tsx b/components/catalog-explorer.tsx
index 4a94b76..4bb1e78 100644
--- a/components/catalog-explorer.tsx
+++ b/components/catalog-explorer.tsx
@@ -122,6 +122,12 @@ function ArtifactSpecimen({
SVG
<ExternalLink aria-hidden="true" />
</a>
+ {artifact.resourceUrl && artifact.resourceLabel && (
+ <a href={artifact.resourceUrl} target="_blank" rel="noreferrer">
+ {artifact.resourceLabel}
+ <ExternalLink aria-hidden="true" />
+ </a>
+ )}
</div>
</div>
</article>
diff --git a/components/guide-evidence.tsx b/components/guide-evidence.tsx
index 1b56f15..17bc7f2 100644
--- a/components/guide-evidence.tsx
+++ b/components/guide-evidence.tsx
@@ -379,6 +379,8 @@ export function GuideHandoff({
skillHref,
artifactLabel = "Open the artifact catalog",
artifactDescription = "Compare the real rendered work.",
+ sourceLabel = "Inspect the source",
+ sourceDescription = "See the brief, states, and implementation.",
skillLabel = "Use the HTML skill",
skillDescription = "Route a real task to the right artifact.",
}: {
@@ -387,6 +389,8 @@ export function GuideHandoff({
skillHref: string;
artifactLabel?: string;
artifactDescription?: string;
+ sourceLabel?: string;
+ sourceDescription?: string;
skillLabel?: string;
skillDescription?: string;
}) {
@@ -398,8 +402,8 @@ export function GuideHandoff({
icon: ArrowUpRight,
},
{
- label: "Inspect the source",
- description: "See the brief, states, and implementation.",
+ label: sourceLabel,
+ description: sourceDescription,
href: sourceHref,
icon: FileCode2,
},
diff --git a/content/docs/decks.mdx b/content/docs/decks.mdx
new file mode 100644
index 0000000..03c10bb
--- /dev/null
+++ b/content/docs/decks.mdx
@@ -0,0 +1,60 @@
+---
+title: Decks
+description: Build a browser-native presentation whose sequence carries the story.
+---
+
+A deck is useful when the order and pace of the explanation matter. HTML makes
+the presentation directly inspectable, interactive, and shareable without
+turning it into a long scrolling page.
+
+## Give each slide one job
+
+Write the sequence before styling it. Each slide should introduce one idea,
+comparison, transition, or piece of evidence. Remove slides that merely repeat
+the speaker, and split slides that ask the audience to parse several arguments
+at once.
+
+## Use a fixed stage
+
+Choose one presentation canvas, usually 16:9, and scale that stage to the
+available viewport. Test the smallest display on which the deck must remain
+readable. Treat the slide as a composition rather than a responsive webpage
+whose elements continuously reflow.
+
+## Keep navigation dependable
+
+Support visible controls and familiar keys. Arrow keys should move through the
+sequence; progress and the current position should remain clear. Preserve
+focus, provide a reduced-motion path, and make full-screen mode optional rather
+than required.
+
+## Use motion to reveal structure
+
+Animation should clarify sequence, comparison, or change. Prefer a few staged
+reveals over constant movement. The deck must still communicate when motion is
+disabled or when it is exported as static pages.
+
+## Package the presentation as an artifact
+
+Keep the deck easy to open and share. A self-contained HTML file is often the
+simplest boundary. If it depends on local media, keep the folder portable and
+make the entry point obvious. Verify keyboard navigation, overflow, external
+links, and static export before presenting.
+
+<GuideHandoff
+ artifactHref="https://thariqs.github.io/html-effectiveness/09-slide-deck.html"
+ artifactLabel="Open the slide-deck example"
+ artifactDescription="Inspect a concise browser-native presentation from The unreasonable effectiveness of HTML."
+ sourceHref="https://github.com/zarazhangrui/frontend-slides"
+ sourceLabel="Study Frontend Slides"
+ sourceDescription="See a complete agent workflow for style discovery, navigation, animation, and export."
+ skillHref="https://github.com/zarazhangrui/frontend-slides/blob/main/SKILL.md"
+ skillLabel="Read the deck skill"
+ skillDescription="Use its implementation rules when a presentation needs more than a one-off example."
+/>
+
+<GuideNext
+ href="/docs/plans"
+ title="Keep implementation work source-grounded"
+ description="Use HTML for a plan only when spatial or interactive structure adds leverage."
+/>
diff --git a/content/docs/diagrams.mdx b/content/docs/diagrams.mdx
index 592af32..0b4e5b3 100644
--- a/content/docs/diagrams.mdx
+++ b/content/docs/diagrams.mdx
@@ -46,7 +46,7 @@ collisions, small text, contrast, and the reading order at narrow widths.
/>
<GuideNext
- href="/docs/plans"
- title="Keep the sequence source-grounded"
- description="Use HTML for a plan only when spatial or interactive structure adds leverage."
+ href="/docs/decks"
+ title="Tell the story as a sequence"
+ description="Use a browser-native deck when pacing and progression carry the explanation."
/>
diff --git a/content/docs/index.mdx b/content/docs/index.mdx
index 2fea44e..c498040 100644
--- a/content/docs/index.mdx
+++ b/content/docs/index.mdx
@@ -18,6 +18,7 @@ Ask what the next human judgment actually is:
- **How should this feel and look?** Make a more resolved mockup.
- **Does this flow behave correctly?** Build a prototype.
- **How do these parts relate?** Draw a diagram.
+- **What story needs deliberate sequence and pacing?** Build a browser-native deck.
- **What sequence preserves the source commitments?** Write a plan.
Higher fidelity is not automatically better. The right artifact is the lowest
@@ -34,9 +35,8 @@ fidelity that answers the current question without creating a new distraction.
## What this guide covers
-The guide starts with the five artifact forms represented in the Effective HTML
-repository: broad HTML artifacts, wireframes, prototypes, plans, and diagrams.
-The examples stay inspectable and source-grounded.
+The guide covers wireframes, prototypes, diagrams, browser-native decks, and
+plans. The examples stay inspectable and source-grounded.
Continue with [why HTML](/docs/why-html), or go directly to
[choosing fidelity](/docs/choosing-fidelity).
diff --git a/content/docs/meta.json b/content/docs/meta.json
index f6bec3d..dcbb469 100644
--- a/content/docs/meta.json
+++ b/content/docs/meta.json
@@ -7,6 +7,7 @@
"wireframes",
"prototypes",
"diagrams",
+ "decks",
"plans"
]
}
diff --git a/lib/catalog-data.ts b/lib/catalog-data.ts
index 3a239c2..d90c0f5 100644
--- a/lib/catalog-data.ts
+++ b/lib/catalog-data.ts
@@ -25,6 +25,8 @@ export type CatalogArtifact = {
title: string;
description: string;
htmlUrl: string;
+ resourceUrl?: string;
+ resourceLabel?: string;
staticSvg: string;
animatedSvg: string;
keywords: string[];
@@ -312,6 +314,8 @@ export const catalogArtifacts: CatalogArtifact[] = [
"Turn source material into a short browser-native presentation with a real sequence and no export step.",
htmlUrl:
"https://thariqs.github.io/html-effectiveness/09-slide-deck.html",
+ resourceUrl: "https://github.com/zarazhangrui/frontend-slides",
+ resourceLabel: "Frontend Slides",
...svgPaths("09-slide-deck"),
keywords: ["slides", "deck", "presentation", "keyboard"],
},