This guide will help you create your first web page using Oat UI. You’ll learn the basics of using semantic HTML with automatic styling.
Your First Oat UI Page
Here’s a complete, working HTML page that demonstrates Oat UI’s core features:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My Oat UI App</title>
<!-- Oat UI CSS and JS -->
<link rel="stylesheet" href="https://unpkg.com/@knadh/oat/oat.min.css">
<script src="https://unpkg.com/@knadh/oat/oat.min.js" defer></script>
</head>
<body>
<main class="container">
<h1>Hello World</h1>
<p>This paragraph is styled automatically with Oat UI.</p>
<!-- Buttons work out of the box -->
<button>Click me</button>
<button data-variant="secondary">Secondary</button>
<button class="outline">Outline</button>
<!-- Alerts use semantic role attribute -->
<div role="alert" data-variant="success">
<strong>Success!</strong> Your changes have been saved.
</div>
<!-- Cards use semantic article tag -->
<article class="card">
<header>
<h3>Card Title</h3>
<p>Card description goes here.</p>
</header>
<p>This is the card content. It can contain any HTML.</p>
</article>
</main>
</body>
</html>
Save this as index.html and open it in your browser. No build step or server required!
Understanding Semantic Styling
Oat UI is designed around semantic HTML. Elements are styled automatically based on their semantic meaning:
Native elements are styled by default
Elements like <button>, <input>, <table>, and headings are styled without any classes:<button>Primary Button</button>
<input type="text" placeholder="Styled automatically" />
<h1>Styled heading</h1>
<p>Styled paragraph with proper spacing.</p>
Use data attributes for variants
Semantic variants use data-variant instead of classes:<button data-variant="primary">Primary</button>
<button data-variant="secondary">Secondary</button>
<button data-variant="danger">Danger</button>
<div role="alert" data-variant="success">Success alert</div>
<div role="alert" data-variant="warning">Warning alert</div>
<div role="alert" data-variant="error">Error alert</div>
Minimal classes for visual styles
Only use classes for visual modifications, not semantic meaning:<button class="outline">Outline style</button>
<button class="small">Small size</button>
<button class="large">Large size</button>
<article class="card">Card container</article>
Complete Example with Multiple Components
Here’s a more comprehensive example showing various Oat UI components:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Oat UI Dashboard</title>
<link rel="stylesheet" href="https://unpkg.com/@knadh/oat/oat.min.css">
<script src="https://unpkg.com/@knadh/oat/oat.min.js" defer></script>
</head>
<body>
<main class="container">
<header>
<h1>Dashboard</h1>
<p class="text-light">Welcome to your Oat UI application</p>
</header>
<!-- Alert Messages -->
<div role="alert" data-variant="success">
<strong>Success!</strong> Your changes have been saved.
</div>
<!-- Grid Layout with Cards -->
<div class="grid">
<article class="card">
<header>
<h3>Light like an oat flake</h3>
</header>
<p><strong>6KB</strong> CSS, <strong>2.2KB</strong> JS, minified + gzipped.</p>
<p>That's it.</p>
</article>
<article class="card">
<header>
<h3>Zero dependencies</h3>
</header>
<p>Fully-standalone with no dependencies on any JS or CSS frameworks or libraries.</p>
</article>
<article class="card">
<header>
<h3>Semantic HTML</h3>
</header>
<p>Native elements like <code><button></code>, <code><input></code>,
<code><dialog></code> are styled directly. No classes.</p>
</article>
</div>
<!-- Form Elements -->
<section>
<h2>Contact Form</h2>
<form>
<label>
Name
<input type="text" placeholder="Enter your name" required />
</label>
<label>
Email
<input type="email" placeholder="your@email.com" required />
</label>
<label>
Message
<textarea placeholder="Your message" rows="4"></textarea>
</label>
<div class="hstack">
<button type="submit">Submit</button>
<button type="reset" class="outline">Reset</button>
</div>
</form>
</section>
<!-- Button Groups -->
<section>
<h2>Button Variations</h2>
<h3>Variants</h3>
<div class="hstack">
<button>Primary</button>
<button data-variant="secondary">Secondary</button>
<button data-variant="danger">Danger</button>
<button class="outline">Outline</button>
<button class="ghost">Ghost</button>
</div>
<h3>Sizes</h3>
<div class="hstack">
<button class="small">Small</button>
<button>Default</button>
<button class="large">Large</button>
</div>
<h3>Button Group</h3>
<menu class="buttons">
<li><button class="outline">Left</button></li>
<li><button class="outline">Center</button></li>
<li><button class="outline">Right</button></li>
</menu>
</section>
<!-- Table -->
<section>
<h2>Data Table</h2>
<table>
<thead>
<tr>
<th>Component</th>
<th>Type</th>
<th>Size</th>
</tr>
</thead>
<tbody>
<tr>
<td>Button</td>
<td>Element</td>
<td>0.5KB</td>
</tr>
<tr>
<td>Card</td>
<td>Element</td>
<td>0.3KB</td>
</tr>
<tr>
<td>Tabs</td>
<td>WebComponent</td>
<td>1.2KB</td>
</tr>
</tbody>
</table>
</section>
</main>
</body>
</html>
Copy this entire example and save it as an HTML file. It demonstrates buttons, cards, forms, tables, and layouts - all working out of the box!
Layout Utilities
Oat UI includes simple layout utilities for common patterns:
Container
<main class="container">
<!-- Content is centered with max-width -->
</main>
Grid System
<!-- Auto-responsive grid -->
<div class="grid">
<div>Column 1</div>
<div>Column 2</div>
<div>Column 3</div>
</div>
<!-- Fixed columns -->
<div class="row">
<div class="col-6">Half width</div>
<div class="col-6">Half width</div>
</div>
Stack Utilities
<!-- Horizontal stack -->
<div class="hstack">
<button>Button 1</button>
<button>Button 2</button>
</div>
<!-- Vertical stack -->
<div class="vstack">
<p>Item 1</p>
<p>Item 2</p>
</div>
Theme Customization
Oat UI automatically supports light and dark themes based on system preferences. The theme uses CSS custom properties that you can override:
:root {
/* Override theme colors */
--primary: #574747;
--background: #fff;
--foreground: #09090b;
--border: #d4d4d8;
/* Spacing */
--space-1: 0.25rem;
--space-2: 0.5rem;
--space-4: 1rem;
/* Border radius */
--radius-small: 0.125rem;
--radius-medium: 0.375rem;
--radius-large: 0.75rem;
}
Oat UI uses the light-dark() CSS function for automatic theme switching. No JavaScript required!
Interactive Components
Some components are Web Components that provide interactive functionality:
<ot-tabs>
<button data-tab="tab1">Tab 1</button>
<button data-tab="tab2">Tab 2</button>
<button data-tab="tab3">Tab 3</button>
<div data-tab-content="tab1">Content 1</div>
<div data-tab-content="tab2">Content 2</div>
<div data-tab-content="tab3">Content 3</div>
</ot-tabs>
Dropdown
<ot-dropdown>
<button popovertarget="menu-id" class="outline">
Menu
</button>
<menu popover id="menu-id">
<a href="#" role="menuitem">Item 1</a>
<a href="#" role="menuitem">Item 2</a>
<a href="#" role="menuitem">Item 3</a>
</menu>
</ot-dropdown>
Toast Notifications
<button onclick="window.ot.toast('Hello!', 'success')">
Show Toast
</button>
<script>
// JavaScript API for toasts
window.ot.toast('Success message', 'success');
window.ot.toast('Error message', 'error');
window.ot.toast('Warning message', 'warning');
window.ot.toast('Info message', 'info');
</script>
Next Steps
Components Reference
Explore all available components with examples
Customization Guide
Learn how to customize themes and styles
Web Components
Deep dive into interactive components
GitHub Repository
View source code and contribute