Buttons and form states
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Design system sections
03 / COMPONENTS
Native interface elements with independent theme previews, markup, selectors, and source references.
Agent Instructions / components
You are composing a current-shell KIRUPA page. Read /design/components.json and the relevant entry in /design/sections/components.md for selectors, variants, source files, and usage. Start from an adjacent working page and reuse its SSI structure and named component classes. When a link needs to look like a link inside the tutorial body, add the blueEmphasis class to its anchor, including in component examples. Style class names, IDs, and code identifiers in explanatory prose with inlineCode. Choose semantic HTML before adding JavaScript. Use visible labels, keyboard-operable controls, clear focus, and explicit loading/error/empty states. Keep forms inert in documentation specimens and label demo output. Preserve the article's reading rhythm and code overflow containment. Verify the component in each visual style and both modes. Do not initialize onboarding, tracking, a live chat request, or a subscription in a preview. Keep reference and navigation descriptions short and factual. Follow WCAG 2.2 AA for new or changed content: semantic HTML, keyboard access, visible focus, readable contrast in every theme, text alternatives, labeled controls, and explicit errors. Support zoom/reflow, respect reduced motion, and keep sound optional. Read /design/sections/accessibility.md for acceptance checks. Report unresolved barriers; automated checks alone do not establish conformance.
Current articles use #mainBody, #mainContent, #tutorialInformation, .authorText, .tutorialInfo, and the shared shell includes. Reuse .kirupaButton, .kirupaInput, .inlineCode, .blueEmphasis, .callout, .articleList, and .embed-container instead of drawing near-duplicates.
Use .blueEmphasis on anchors that need the standard link treatment inside tutorial body content, including links in component examples. Keep their text descriptive. Use .inlineCode when naming CSS classes, IDs, or code identifiers in the explanation.
Example: Use the reading classes directly
Give the identifier its inline-code treatment and the destination its link treatment.
<p>Change <span class="inlineCode">count</span>, then
<a class="blueEmphasis" href="/html5/building_your_first_web_page.htm">try the example</a>.
</p>Use real buttons for actions, anchors for destinations, visible input labels, scope on table headers, and a caption or accessible name for tables. Focus is a state, not an optional decoration. Label disabled controls and empty states so readers understand what can happen next.
Tutorial content has a title and byline, a reason to care, an example, and a clear progression. Code and illustrations must agree. Long examples can scroll inside their own container; the whole page must not become a sideways adventure. Here is a reading detail from Building Your First Interactive Web Page:
Reading patterns in a real tutorial
The screenshot could not load. Open the live example or the full-size image below.
The theme picker is a dialog with color swatches, a custom color, mode choices, and style cards. Onboarding is a separate once-only interaction that can record choices. These are production behaviors, not things to initialize when showing an innocent design preview.
The catalog below covers shared article patterns, navigation, book and newsletter promotions, theme controls, search, chat, media, and the visitor globe. Each entry identifies its implementation and any preview limitations. Tutorial-specific games and visualizers, legacy Flash interfaces, and third-party Discourse internals are outside this shared-component catalog. Preview actions stay local; they never submit a subscription, chat message, search query, or presence event to production.
- Do keep labels short, specific, and verb-led: Play, Stop, Download, Copy instructions.
- Do distinguish loading, empty, success, and error states in text, not color alone.
- Do not turn every paragraph into a card or use arbitrary decorative separators.
Component catalog
Current shared tutorial elements, homepage and podcast cards, promotions, navigation, theme controls, and signature widgets. Examples reuse native CSS and extracted source markup. Lesson-specific demos, legacy Flash layouts, and the unversioned Discourse theme are not a shared component library. Download component metadata.
Article title and metadata
Native article title, author block, and Filed under metadata.
Article title and metadata
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Keep the shared title size and font. Do not introduce a separate hero or display treatment.
Markup, selectors, and sources
Selectors: #tutorialInformation, .authorText, .tutorialInfo
Properties: --headerText, --bodyText
Article title and metadata
<div id="tutorialInformation">
<div class="authorText">
<h1>Your article title</h1>
<p class="tutorialInfo">Filed under <a class="blueEmphasis" href="/html5/learn_html_css.htm">HTML and CSS</a></p>
</div>
</div>Example composed with native selectors. Rendered markup
ssi/newDesign/src/kirupa.cssdesign/template.htmhtml5/building_your_first_web_page.htmHeadings, links, code, and emphasis
Article heading levels and inline treatments using the site's existing selectors.
Headings, links, code, and emphasis
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Links that need to look like links in tutorial body content require blueEmphasis. Use inlineCode for identifiers; do not apply it to a whole code block.
Markup, selectors, and sources
Selectors: #mainContent h2, #mainContent h3, #mainContent h4, .blueEmphasis, .inlineCode, strong, em
Properties: --serifFonts, --monoFonts, --headerText, --linkForeground, --linkHoverBackground
Headings, links, code, and emphasis
<h2>Section heading</h2>
<p>Read <a class="blueEmphasis" href="/path/example.htm">the example</a>.
Use <code class="inlineCode">value</code> for an identifier.</p>
<h3>Subsection heading</h3>Example composed with native selectors. Rendered markup
ssi/newDesign/src/kirupa.cssButtons and size variants
Primary actions, the historical greenButton alias, and the compact button modifier.
Buttons and size variants
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Use buttons for actions and anchors for navigation. greenButton is a historical name; its color follows the palette. The compact modifier does not guarantee a 44px touch target. Check focus, disabled behavior, and hit area in the actual context.
Markup, selectors, and sources
Selectors: .kirupaButton, .greenButton, .kirupaButtonSmall
Properties: --primary, --primaryDarker, --textOnPrimary
Buttons and size variants
<button type="button" class="kirupaButton">Run example</button>
<a class="greenButton" href="/path/example.htm">Open reference</a>
<button type="button" class="kirupaButton kirupaButtonSmall">Compact</button>Example composed with native selectors. Rendered markup
ssi/newDesign/src/kirupa.cssArticle lists and ordered steps
Native linked topic lists, ordinary bullet lists, and ordered instructions.
Article lists and ordered steps
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
articleList has its own link and icon treatment. Ordinary inline reading links still use blueEmphasis. Keep list semantics instead of imitating bullets with text.
Markup, selectors, and sources
Selectors: .articleList, #mainContent ul, #mainContent ol
Properties: --bodyText, --primary, --linkForeground
Article lists and ordered steps
<ul class="articleList">
<li><a href="/html5/functions_in_javascript.htm">Functions</a></li>
</ul>
<ol><li>First step</li><li>Second step</li></ol>Example composed with native selectors. Rendered markup
ssi/newDesign/src/kirupa.cssjavascript/learn_javascript.htmNotes, downloads, and archive notices
Three existing callout patterns with different purposes.
Notes, downloads, and archive notices
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
A note explains an exception; a download callout exposes a file; an archive notice prevents an old pattern being mistaken for current guidance.
Markup, selectors, and sources
Selectors: .callout, .downloadCallout, .legacyArchiveNote
Properties: --highlighter, --lighter, --darkTextSecondary
Note
<aside class="callout"><p><strong>Note title</strong></p><p>Necessary context.</p></aside>Example composed with native selectors. Rendered markup
Download
<div class="downloadCallout">
<img src="/pixel_icons/save.gif" width="48" height="48" alt="">
<p><a class="blueEmphasis" href="/path/example.svg" download>Download SVG</a></p>
</div>Example composed with native selectors. Rendered markup
Archive notice
<aside class="legacyArchiveNote"><p>Explain the archive status and link to the current reference.</p></aside>Example composed with native selectors. Rendered markup
ssi/newDesign/src/kirupa.cssdesign/archive.htmSyntax-highlighted code
Native Prism code presentation, including real highlighting and overflow behavior.
Syntax-highlighted code
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Put the language on both pre and code so the unhighlighted block has stable geometry. The normal shell loads Prism near the viewport; the isolated example loads the same library explicitly.
Markup, selectors, and sources
Selectors: pre[class*="language-"], code[class*="language-"], .token
Properties: --monoFonts, --codeFilter
Syntax-highlighted code
<pre class="language-javascript"><code class="language-javascript">const count = 3;</code></pre>Example composed with native selectors. Rendered markup
ssi/newDesign/src/kirupa.cssssi/newDesign/src/kirupa.jsjs/prism_v1.jsImages and embedded-media frames
Bordered images, borderless artwork, and the shared iframe frame.
Images and embedded-media frames
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Introduce figures in the surrounding prose. Preserve intrinsic dimensions and purposeful alt text. The embed preview only demonstrates the frame; it does not load a player or third-party service.
Markup, selectors, and sources
Selectors: .centerImage, .centerImageNoBorder, .centerIframe, .imageCaption
Properties: --mediaBorder
Bordered image
<p class="centerImage"><img src="/path/image.png" width="640" height="360" alt="The point of the image."></p>Example composed with native selectors. Rendered markup
Borderless illustration
<p class="centerImageNoBorder"><img src="/path/diagram.svg" width="600" height="400" alt="The relationship illustrated." style="background:#fff"></p>Example composed with native selectors. Rendered markup
Embedded-media frame
<div class="centerImage">
<iframe title="Descriptive player title" width="560" height="315" src="YOUR_APPROVED_EMBED_URL" loading="lazy" allowfullscreen></iframe>
</div>Example composed with native selectors. Rendered markup
ssi/newDesign/src/kirupa.cssdata_structures_algorithms/understanding_merkle_trees.htmBook promotions
Inline book callouts and the older cover-and-copy book blocks.
Book promotions
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Markup and inline styles are extracted from the real includes. Render one variant at a time because several share IDs. 3dBook.shtml currently repeats the animation promotion; it is not a separate 3D-book design. Older includes may need accessibility and mobile updates before reuse.
Markup, selectors, and sources
Selectors: #kbook_callout, .lightbulb_callout, .lightbulb, .bookContent, #bookImage, #bookContent, .greenButton
Properties: --lighter, --light, --primaryLightest, --mediaBorder
Data Structures and Algorithms
<!--#include virtual="/ssi/newDesign/inline_algorithms.shtml"-->Source-extracted markup. Rendered markup
JavaScript
<!--#include virtual="/ssi/newDesign/jsBook.shtml"-->Source-extracted markup. Rendered markup
Canvas
<!--#include virtual="/ssi/newDesign/canvasBook.shtml"-->Source-extracted markup. Rendered markup
Arrays
<!--#include virtual="/ssi/newDesign/arrayBook.shtml"-->Source-extracted markup. Rendered markup
React
<!--#include virtual="/ssi/newDesign/reactBook.shtml"-->Source-extracted markup. Rendered markup
Web Animation
<!--#include virtual="/ssi/newDesign/animBook.shtml"-->Source-extracted markup. Rendered markup
ssi/newDesign/inline_algorithms.shtmlssi/newDesign/jsBook.shtmlssi/newDesign/canvasBook.shtmlssi/newDesign/arrayBook.shtmlssi/newDesign/reactBook.shtmlssi/newDesign/animBook.shtmlssi/newDesign/3dBook.shtmlssi/newDesign/src/kirupa.cssInline newsletter callout
Mail artwork, newsletter copy, and a linked action inside an article.
Inline newsletter callout
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Reuse the include and its ID so style-specific artwork remains attached. The preview never subscribes or opens the newsletter service.
Markup, selectors, and sources
Selectors: #newsletter_callout
Properties: --lighter, --light, --mediaBorder
Inline newsletter callout
<!--#include virtual="/ssi/newDesign/inline_newsletter.shtml"-->Source-extracted markup. Rendered markup
ssi/newDesign/inline_newsletter.shtmlssi/newDesign/src/kirupa.cssHeader and utility controls
KIRUPA branding, animated background, visitor count, and header controls.
Header and utility controls
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
The preview runs the real visual scripts with fictional visitor data. Navigation and sound actions are local demonstrations. The production include retains its normal behavior.
Markup, selectors, and sources
Selectors: #mainHeader, #backgroundHeader, #soundToggle, #onlineCountLink
Properties: --headerBackground, --logoTextColor, --primary
Header and utility controls
<!--#include virtual="/ssi/newDesign/header.shtml"-->Tutorial left navigation
Native section headings, topic links, and current-article state.
Tutorial left navigation
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
The preview reveals the desktop rail inside a bounded scroll region even at a small iframe width. It preserves the real link formatting. The live shell hides the rail at its responsive breakpoint.
Markup, selectors, and sources
Selectors: .leftNavContainer, .leftNav, .leftNavContents, .currentArticle
Properties: --leftNavLight, --structureBorder, --bodyText
Tutorial left navigation
<!--#include virtual="/ssi/newDesign/left_js.shtml"-->
<!-- The shared controller marks the matching URL with currentArticle. -->Source-extracted markup. Rendered markup
ssi/newDesign/left_js.shtmlssi/newDesign/src/kirupa.cssdesign/template.htmHomepage content cards
Latest-content cards for tutorials, the newsletter, podcasts, and forum discussions.
Homepage content cards
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Each variant is an actual homepage card with the homepage's inline CSS. Text is the checked-in snapshot, not a live feed. The scoped latest-* tokens belong to this component, not the global token set.
Markup, selectors, and sources
Selectors: #latest, .latest-card, .latest-card-heading, .latest-art, .latest-posts, .latest-more
Properties: --latest-panel, --latest-ink, --latest-radius, --latest-shadow
Tutorials
<section id="latest">
<!-- Reuse the latest-card structure and scoped CSS from index.html. -->
</section>Source-extracted markup. Rendered markup
Newsletter
<section id="latest">
<!-- Reuse the latest-card structure and scoped CSS from index.html. -->
</section>Source-extracted markup. Rendered markup
Podcasts
<section id="latest">
<!-- Reuse the latest-card structure and scoped CSS from index.html. -->
</section>Source-extracted markup. Rendered markup
Forum discussions
<section id="latest">
<!-- Reuse the latest-card structure and scoped CSS from index.html. -->
</section>Source-extracted markup. Rendered markup
index.htmlTheme customizer
Native style cards, palette swatches, custom-color input, and mode controls.
Theme customizer
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Markup is generated by the native dialogMarkup function without running its persistence controller. Form controls demonstrate local selection only; the controls above the preview set its actual theme. Closing or resetting this example never changes saved site preferences.
Markup, selectors, and sources
Selectors: #themeWrapper, #themePanel, .themeStyles, .themeSwatches, .themeSegments
Properties: --themeCardBg, --mediaBorder, --primary
Theme customizer
<!-- Include the shared head, header, and footer.
The shared kirupa.js controller builds #themeWrapper and owns persistence.
Do not copy that controller into a locally themed specimen. -->Generated from the native source. Rendered markup
ssi/newDesign/src/kirupa.jsssi/newDesign/src/kirupa.cssSearch dialog
The real search interface with a local result provider and keyboard navigation.
Search dialog
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Open the dialog and search for grid or code. Results are local fixtures and search storage stays in memory within the preview; no query, analytics event, or saved-search entry is sent to production. Escape closes the example.
Markup, selectors, and sources
Selectors: .DocSearch-Button, .DocSearch-Modal, .DocSearch-Input, .DocSearch-Hit
Properties: --pageBackground, --bodyText, --primary, --docsearch-muted-color
Search dialog
<!-- Use the search opener and lazy loader supplied by the shared footer.
Do not duplicate production transport configuration in an embedded demo. -->kirupaBot launcher and chat panel
Launcher, welcome message, composer, answer, loading, and error states.
kirupaBot launcher and chat panel
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Select each state in the example or type a local demo message. Responses are fixtures. No real question is sent and no chat history is persisted.
Markup, selectors, and sources
Selectors: #kirupabot-widget, .kbw-launcher, .kbw-panel, .kbw-message, .kbw-typing
Properties: --primary, --bodyText, --inputBackground
kirupaBot launcher and chat panel
<!-- The shared footer loads kirupabot-widget.js and its stylesheet.
Use the existing launcher/panel implementation; do not mount it twice. -->Visitor globe and table
Real globe renderers with visitor markers and a semantic location table.
Visitor globe and table
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Uses the actual renderers with fictional locations and no presence service. Preserve an accessible text/table equivalent and honor reduced motion.
Markup, selectors, and sources
Selectors: #clayGlobeStage, #clayGlobe, .clay-presence-table, .clay-table-location
Properties: --pageBackground, --bodyText, --primary, --structureBorder
Visitor globe and table
<!-- Reuse the stage, renderer, and table structure from whos-online/index.php.
Keep production presence collection separate from display-only fixtures. -->Podcast index card
Episode artwork, guest name, title, date, and duration.
Podcast index card
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
The example extracts the actual first card and scoped CSS from the podcast index. A cover that repeats the neighboring title can use empty alt text.
Markup, selectors, and sources
Selectors: .podcastGrid, .podcastCard, .podcastCardCopy, .podcastGuest, .podcastRuntime
Properties: --structureBorder, --pageBackground, --bodyText, --primaryLighter
Podcast index card
<ul class="podcastGrid">
<li class="podcastCard"><a href="/podcast/episode.htm">
<img src="/podcast/images/episode.jpg" alt="">
<span class="podcastCardCopy">
<span class="podcastGuest">Guest name</span>
<strong>Episode title</strong>
<span class="podcastRuntime">Date and duration</span>
</span>
</a></li>
</ul>Source-extracted markup. Rendered markup
podcast/index.htmEpisode media
A real interview cover in a locally themed media context.
Episode media
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
The photograph is fixed artwork. The example is a cover and episode link, not a working video player.
Markup, selectors, and sources
Selectors: .centerImage, .centerImageNoBorder
Properties: --mediaBorder, --pageBackground
Episode media
<!-- Reuse the podcast page renderer and template for new episodes.
Do not hand-copy an episode page or auto-start its player. -->Short-form video and captions
Caption placement and real portrait or square video reference frames.
Short-form video and captions
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
This is an export pattern, not a CSS component. The caption font is author-confirmed but not bundled; the layout diagram labels its fallback. No video or audio starts.
Markup, selectors, and sources
Short-form video and captions
<!-- Use the kirupa-podcast highlight workflow for captioned exports.
Caption font: Born2bSportyV10, not Permanent Marker or Born2bSporty v2. -->Forum post structure
Author identity, post content, code, spacing, and visible bot labeling.
Forum post structure
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Explicitly a layout contract with fictional posts, not a copy of the live Discourse theme or a reusable Discourse plugin.
Markup, selectors, and sources
Forum post structure
<!-- Read /design/sections/forums.md and the captured live forum examples.
The current Discourse theme is not versioned in this repository. -->Agent Instructions disclosure
The design reference's collapsible, copyable prompt with direct Markdown and text downloads.
Agent Instructions disclosure
LOCAL PREVIEWActivate this specimen to load its real styles. No saved preferences change.
Use the generator's shared disclosure, not a separate copy of the prompt. The example supports native expand/collapse and local clipboard copying; the outer page's instructions remain independent.
Markup, selectors, and sources
Selectors: .agent-instructions, .action-row, [data-copy]
Properties: --inputBorder, --primaryLightest, --darkTextSecondary
Agent Instructions disclosure
<details class="agent-instructions">
<summary>Agent Instructions <span> / section-id</span></summary>
<p id="prompt-section-id">Task-scoped instructions.</p>
<div class="action-row">
<button type="button" data-copy="prompt-section-id">Copy instructions</button>
<a class="blueEmphasis" href="/design/agent/section-id.txt" download>Download prompt</a>
</div>
</details>Generated from the native source. Rendered markup
tools/build_design_system.mjsdesign/design.cssdesign/design.js