Semanticwind reference

A style reference, guidance for choosing the right element, and browser-native alternatives to common components.

Contents

Element reference

The native elements where Semanticwind supplies a visible baseline.

The surrounding documentation shell owns its page layout. Specimens below remain classless so their content styling comes from Semanticwind itself.

Text and structure

Document rhythm, typography, lists, code, and quotations.

Document structure

<article> <aside> <address> <search>

Structure receives readable rhythm without becoming a product component.

A small release note

Published August 28, 2026

The browser keeps the document meaning while Semanticwind supplies the baseline.

Maintained by Ike Tiunn
Taipei, Taiwan

Search field example

Heading hierarchy

<hgroup> <h1>–<h6>

Balanced sizes establish hierarchy without requiring utility classes.

Grouped heading

A heading and its supporting line.

Heading level one

Heading level two

Heading level three

Heading level four

Heading level five

Heading level six

Text and links

<p> <a> <strong> <mark>

Select this text and interact with the links to exercise native states.

A paragraph can contain a normal link, an active link, strong importance, visual attention, highlighted text, and small print.

HTML can show ~~removed copy~~, inserted copy, H₂O, x², a defined term, version 0.1.0, and element.

Lists

<ul> <ol> <dl>

Nested and descriptive lists retain useful spacing and hierarchy.

Semantic markup first
Utilities for local decisions
- Layout
- Responsive behavior
Components for repeated product meaning

Link Semanticwind.
Write ordinary HTML.
Add utilities when needed.

Baseline: Broadly useful native defaults.
Escape hatch: Tailwind utilities and explicit components.

Code and quotations

<code> <kbd> <samp> <blockquote>

Inline and block code remain readable without a syntax-highlighting dependency.

Run npm run build, press ⌘ + K, and expect Done in 48ms.

@import "tailwindcss";
@import "semanticwind";

Would this style make sense for almost every correct use of this element?
Semanticwind’s boundary test

Divider and captioned content

<hr> <figure> <figcaption>

A figure can caption code, quotations, or data—not only images.

Before the thematic break.

<button>Publish</button>

A native button needs no component wrapper to receive the baseline.

Tables

One complete specimen covers the table baseline and its responsive overflow.

Structured data

<table> <caption> scope

A caption names the table and scope connects its headers. Keep the structure simple; if an app adds a separate scroll region, give that region an accessible name.

Recent package checks
Check	Result	Duration
Build	Passed	48 ms
Browser	Passed	1.2 s
Package	Passed	320 ms
Total	3 passed	1.568 s

Forms

Classless flow, native controls, states, choices, and actions.

Classless form flow

<form> <label> <button>

A form without a class gets useful prototype spacing and full-width controls.

Text-like controls

<input>

Common text inputs share one neutral, focusable baseline.

Long-form and selection

<textarea> <select> <optgroup>

Text areas and native selection remain browser-owned and responsive.

Choices

checkbox radio

Checked, unchecked, focused, and disabled states remain native.

Control states

readonly disabled aria-invalid

State colors reinforce behavior without replacing labels or help text.

Actions

<button> submit reset

Native buttons share clear targets, focus, active, and disabled states.

Specialized controls

Interactive elements

Disclosure, top-layer surfaces, progress, measurement, and commands.

Disclosure

<details> <summary>

Open and closed states remain understandable without scripting.

Closed disclosure

This content appears when the summary is activated.

Open disclosure

The browser owns activation, keyboard handling, and state.

Dialog

<dialog>

Modal dialogs receive a strong backdrop and constrained surface.

Progress and measurement

<progress> <meter>

Progress shows completion; meter evaluates a value within a known range.

Build progress72%Checking dependenciesChecking dependencies…Quality score · 86 / 10086%Review score · 62 / 10062%Coverage score · 28 / 10028%

Extra: Use the right element

Choose HTML by its meaning and relationships, not its default appearance.

Start with a complete document

<!doctype> lang <meta> <title>

Start in standards mode, declare the language and encoding, allow responsive rendering and zoom, give every page a useful title, and keep one main landmark with a real heading hierarchy.

web.dev: Document structure · Headings and sections

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Unique page title</title>
  </head>
  <body>
    <main>
      <h1>Unique page heading</h1>
    </main>
  </body>
</html>

Structure standalone content

<article> <header> <footer> <aside>

Use an article for content that can stand on its own; use an aside only when its meaning depends on nearby content.

Release notes

Version 0.1.0

Semanticwind now styles native progress and meter elements.

View markup

<article>
  <header><h2>Release notes</h2></header>
  <p>Standalone content.</p>
  <footer>Publication details.</footer>
</article>

Caption related content

<figure> <figcaption> <caption>

Use captions when content needs a name or explanation that remains attached to it.

Start with the platform.

A principle quoted from the Semanticwind guide.

View markup

<figure>
  <blockquote>Start with the platform.</blockquote>
  <figcaption>Source and context.</figcaption>
</figure>

Author a responsive image

<img> alt srcset sizes

Let the browser choose an appropriate source. Intrinsic dimensions reserve space; meaningful alternative text explains purpose; lazy loading belongs only on images below the fold.

web.dev: Images · Responsive images

<img
  src="report-800.webp"
  srcset="report-400.webp 400w, report-800.webp 800w"
  sizes="(max-width: 40rem) 100vw, 40rem"
  width="800"
  height="500"
  alt="Quarterly revenue by region"
  loading="lazy"
>

Use alt="" for a decorative image. Use <picture> only for alternate formats or art direction, with a fallback <img>.

Describe terms and values

<dl> <time> <data>

Prefer machine-readable values when a date, identifier, or definition has meaning beyond its display text.

Released: August 28, 2026
Version: Semanticwind 0.1.0

View markup

<dl>
  <div><dt>Released</dt><dd><time datetime="2026-08-28">August 28</time></dd></div>
</dl>

Label and group controls

<label> <fieldset> <legend> <output>

Labels name individual controls; a fieldset and legend name the relationship between them.

View markup

<fieldset>
  <legend>Delivery speed</legend>
  <label><input type="radio" name="delivery"> Standard</label>
</fieldset>

Author a complete field

<label> name type autocomplete aria-describedby

A label names the control, name identifies submitted data, type and autocomplete unlock browser behavior, and visible help stays connected. A placeholder is never the label.

web.dev: Form fields · Autofill · Accessibility

View markup

<label for="email">Email address</label>
<input
  id="email"
  name="email"
  type="email"
  autocomplete="email"
  aria-describedby="email-help"
>
<small id="email-help">We will send the receipt here.</small>

Choose the correct field state

readonly disabled required

Read-only values remain focusable and submitted; disabled values do neither. Explain invalid input in visible text.

View comparison markup

<input name="account-id" value="SW-1042" readonly>
<input name="legacy-id" value="Unavailable" disabled>
<input type="email" required aria-invalid="true" aria-describedby="email-error">
<small id="email-error">Error: Enter a complete email address.</small>

Distinguish progress from measurement

<progress> <meter>

Progress reports task completion. Meter evaluates a scalar value against a known range.

Upload progress65%Storage usage · 65 / 10065%

View comparison markup

<progress value="65" max="100">65%</progress>
<meter min="0" max="100" low="50" high="85" value="65">65%</meter>

Test the baseline before adding a dependency

keyboard zoom dir pointer

Native HTML removes work, but authors still need to test their content and composition.

web.dev: Accessibility · Internationalization · Interaction

Keyboard: keep DOM, visual, and tab order aligned; avoid positive tabindex.
Zoom: check 200% and 400%; content should reflow instead of clip.
Language: set lang, test dir="rtl", and allow translated labels to grow.
Input: pair hover with focus and test keyboard, touch, coarse, and fine pointers.
Layout: choose breakpoints where content stops working, not from a device catalog.

Extra: Browser-native first

Before installing a dependency, use browser-owned semantics and behavior. Add custom UI only when a proven requirement outgrows native capability, support, or control.

Inline help

aria-describedby <small>

Keep instructions visible when people need them to finish the task. Use a user-invoked popover only when the detail is genuinely optional.

Release name Available to pointer, keyboard, touch, and assistive-technology users.

View markup

<label for="release-name">Release name</label>
<input id="release-name" aria-describedby="release-name-help">
<small id="release-name-help">Visible instructions.</small>

FAQ accordion

<details name>

Newer support · Can I Use

Use a shared name when only one answer should stay open. Older supported browsers keep both disclosures independently usable. Add a component when routing, controlled state, or custom animation is required.

What does Semanticwind style?

Native HTML elements with broadly useful defaults.

When should I add a component?

When repeated product meaning or custom behavior appears.

View markup

<details name="faq" open>...</details>
<details name="faq">...</details>

Optional help

popover popovertarget

Broad support · Can I Use

Use a regular popover for optional information people deliberately request; the browser owns activation, the top layer, light dismissal, and Escape, while the application owns placement. Use a dialog when the user must respond.

Press ⌘ + Enter to publish.

View markup

<button popovertarget="shortcut-help">Keyboard shortcut</button>
<div id="shortcut-help" popover>Press ⌘ + Enter to publish.</div>

Publish confirmation

<dialog> commandfor

Broad support: dialog · Newer support: commands

Use a modal dialog when the user must respond before returning to the page; the browser manages focus and the inert background.

View markup

<button commandfor="confirm" command="show-modal">Open</button>
<dialog id="confirm">
  <h4>Publish release?</h4>
  <form method="dialog">
    <button value="cancel">Cancel</button>
    <button value="publish">Publish</button>
  </form>
</dialog>

Native form controls

date color range <output>

Mixed support · Date and time · Color · Range

Use platform pickers when native appearance and graceful fallback are acceptable. Go custom only when a required interaction is unavailable.

View markup

<input type="date">
<input type="color">
<input id="confidence" type="range">
<output for="confidence">72</output>

Project suggestions

<datalist>

Limited support · Can I Use

Use datalist for lightweight suggestions that still allow free text. Choose a custom combobox for large data, reliable styling, or stronger assistive behavior.

Project

View markup

<input list="projects">
<datalist id="projects">
  <option value="Customer portal">
</datalist>

Grouped heading

Heading level one

Heading level two

Heading level three

Heading level four

Heading level five

Heading level six

Native popover