100+ copy-paste UI components in plain HTML and CSS: no dependencies, no build step.
Semantic Web Components Library
Version 1.0.0 - Intent-based, context-aware, modality-agnostic UI components
What Makes This Different
Bootstrap/Material/Tailwind:
<button class="btn btn-primary" onclick="save()">Save</button>
Problem: Specifies HOW (styling), not WHAT (intent). Breaks with CSS changes. No context awareness.
This Library:
<semantic-action intent="primary" sentiment="constructive">Save</semantic-action>
Solution: Specifies WHAT the user wants to do. Automatically adapts to context, modality, and attention budget.
Core Principles
- Intent Over Implementation - Declare what users want to DO, not how to render it
- Context-Aware by Default - Components adapt to environment automatically
- Modality-Agnostic - Works across mouse, touch, voice, keyboard, AR
- Attention Budget - Components negotiate for limited user attention
- Future-Proof - Semantic versioning ensures no breaking changes
Installation
<!-- Include the library -->
<script src="semantic-components.js"></script>
<!-- Start using components -->
<semantic-action intent="primary">Click Me</semantic-action>
No build step. No framework required. Just works.
Components
1. <semantic-action> - User Actions
Replaces: Buttons, links, clickable divs
Attributes:
intent:primary|secondary|tertiary- Interaction importancesentiment:constructive|destructive|neutral- Action sentimentdisabled: Boolean - Disabled state
Events:
activate- User wants to perform action (click, tap, voice command)inspect- User wants to preview action (hover, long-press)
Example:
<semantic-action intent="primary" sentiment="constructive">
Save Document
</semantic-action>
<semantic-action intent="secondary" sentiment="destructive">
Delete
</semantic-action>
<script>
document.querySelector('semantic-action').addEventListener('intent', (e) => {
if (e.detail.type === 'activate') {
console.log('User activated action');
}
});
</script>
Automatic Features:
- Mouse: Hover effects, click handling
- Touch: Large tap targets (44px min), long-press for inspect
- Keyboard: Full navigation, Enter/Space to activate
- Voice: Registers command based on text content
- Focus: Visible focus indicators
- Accessibility: Full ARIA support built-in
2. <semantic-card> - Inspectable Content
Replaces: Card components, tiles, list items
Attributes:
media-url: Image URLmedia-alt: Image alt text
Slots:
media-icon: Icon when no image (default slot)title: Card titledescription: Card descriptionpreview: Preview content (shown on inspect)actions: Action buttons
Events:
activate- Navigate to contentinspect- Preview content
Example:
<semantic-card>
<span slot="media-icon">🚀</span>
<card-title slot="title">Project Alpha</card-title>
<card-description slot="description">
Next-gen platform
</card-description>
<div slot="preview">
Preview: Full details here
</div>
<div slot="actions">
<semantic-action intent="tertiary">Share</semantic-action>
<semantic-action intent="tertiary">Edit</semantic-action>
</div>
</semantic-card>
Automatic Features:
- Mouse: Hover to preview, click to navigate
- Touch: Long-press to preview, tap to navigate
- Voice: "Inspect [title]" or "Open [title]"
- Keyboard: Tab to focus, Enter to navigate
- Accessibility: Article role, screen reader optimized
3. <semantic-adjuster> - Value Control
Replaces: Sliders, number inputs, steppers
Attributes:
label: Control labelvalue: Current valuemin: Minimum value (default: 0)max: Maximum value (default: 100)step: Step increment (default: 1)
Properties:
value: Get/set current value
Events:
adjust- Value changed
Example:
<semantic-adjuster
label="Volume"
value="50"
min="0"
max="100"
step="5">
</semantic-adjuster>
<script>
const adjuster = document.querySelector('semantic-adjuster');
adjuster.addEventListener('intent', (e) => {
if (e.detail.type === 'adjust') {
console.log('New value:', e.detail.value);
}
});
</script>
Automatic Features:
- Mouse: Click buttons, drag slider
- Touch: Tap buttons, swipe slider
- Voice: "Increase volume", "Set volume to 75"
- Keyboard: Arrow keys, +/- keys
- Accessibility: Full ARIA slider support
4. <semantic-feedback> - Notifications
Replaces: Toasts, alerts, modals, notifications
Attributes:
urgency:critical|high|medium|lowtype:notification|alert|confirmationauto-dismiss: Boolean - Auto-dismiss after 5scan-defer: Boolean - Can be deferred when user busysensitivity:private|public- Privacy level
Slots:
icon: Custom icon- Default: Message content
Events:
dismiss- User dismissed notification
Example:
<semantic-feedback urgency="critical" type="alert">
<span slot="icon">⚠️</span>
Security alert requires attention
</semantic-feedback>
<semantic-feedback urgency="low" can-defer="true" auto-dismiss>
Software update available
</semantic-feedback>
Automatic Features:
- Attention Budget: Prioritized by urgency
- Context-Aware: Defers if user busy/focused
- Privacy: Hides sensitive content with multiple viewers
- Multi-Modal: Visual + audio + haptic based on context
- Accessibility: Alert role, screen reader optimized
Context Management
Global Context Manager
// Access global context
const context = window.semanticContext;
// Change modality
context.setModality('voice-screen'); // 'screen' | 'voice-screen' | 'voice-only' | 'touch'
// Update environment
context.updateContext({
environment: {
noiseLevel: 80, // 0-100
viewerCount: 3, // Number of people viewing
isPublic: true, // Public display mode
lighting: 'dark' // 'bright' | 'normal' | 'dark'
},
user: {
isBusy: true, // User in active task
inFocusMode: true, // Do not disturb mode
prefersReducedMotion: false
}
});
// Listen to context changes
context.onChange((newContext) => {
console.log('Context changed:', newContext);
});
Automatic Context Adaptation
Components automatically adapt based on context:
User Busy:
- Non-critical notifications deferred
- Attention scores reduced for low-priority items
Focus Mode:
- Only critical items shown
- All low-urgency items hidden
Multiple Viewers:
- Private content (
sensitivity="private") auto-hidden - Sensitive information blurred
High Noise Environment:
- Visual feedback emphasized
- Confirmation required for critical actions
Public Display:
- Personal information hidden
- Auto-timeout on inactivity
Attention Budget System
Components compete for limited resources:
Resources:
- Screen Space: 0-100% of viewport
- Audio Time: 0-10 seconds for voice output
- Cognitive Load: 0-3 simultaneous attention points
Component Attributes:
<semantic-feedback
urgency="high"
priority="time-sensitive"
attention-weight="80"
screen-space="15"
audio-time="4"
cognitive-load="1">
Meeting in 5 minutes
</semantic-feedback>
Priority Scoring:
score = (urgency × urgency_multiplier) +
(priority × priority_weight) +
(time_sensitivity × time_weight) -
(user_disruption × disruption_penalty)
Allocation States:
allocated- Component gets attentiondeferred- Pushed to later (ifcan-defer="true")hidden- Completely hidden based on context
Check state:
const component = document.querySelector('semantic-feedback');
const state = component.getAttribute('attention-state');
// 'allocated' | 'deferred'
Styling & Theming
CSS Parts (Shadow DOM)
Each component exposes parts for styling:
/* Style action buttons */
semantic-action::part(button) {
font-family: 'Custom Font';
border-radius: 16px;
}
/* Style card elements */
semantic-card::part(card) {
border-radius: 20px;
}
semantic-card::part(media) {
border-radius: 16px 16px 0 0;
}
Available Parts:
semantic-action:
button- The button element
semantic-card:
card- Main card containermedia- Image elementmedia-placeholder- Placeholder if no imagecontent- Content areaactions- Action buttons areapreview- Preview overlay
semantic-adjuster:
adjuster- Main containerlabel- Label textvalue- Value displaydecrease- Decrease buttonincrease- Increase buttonslider- Slider track
semantic-feedback:
feedback- Main containericon- Icon areacontent- Message contentdismiss- Dismiss button
Migration Guide
From Bootstrap/Material/Tailwind:
Before:
<button class="btn btn-primary btn-lg" onclick="save()">
Save
</button>
After:
<semantic-action intent="primary">
Save
</semantic-action>
From Custom Components:
Before:
<div class="card" onclick="navigate()">
<img src="image.jpg">
<h3>Title</h3>
<p>Description</p>
</div>
<script>
// Manual hover handling
// Manual touch handling
// Manual accessibility
// Manual responsive behavior
</script>
After:
<semantic-card media-url="image.jpg">
<card-title slot="title">Title</card-title>
<card-description slot="description">Description</card-description>
</semantic-card>
<script>
// All interactions handled automatically
// Full accessibility built-in
// Context-aware by default
</script>
Browser Support
- Chrome/Edge: 90+
- Firefox: 88+
- Safari: 14+
- Mobile: iOS 14+, Android Chrome 90+
Requires: Custom Elements, Shadow DOM, ES6
Roadmap
v1.1
<semantic-navigator>- Navigation patterns<semantic-input>- Form inputs<semantic-layout>- Adaptive layouts
v1.2
- Voice command registration API
- AR/spatial interaction support
- Gesture library
v2.0
- Component versioning system
- Backward compatibility layer
- Extended context sensors (location, time, device capabilities)
Philosophy
This isn't just another component library. It's a paradigm shift.
Traditional approach: Build for mouse, add touch later, maybe consider accessibility Semantic approach: Build for INTENT, system handles modality automatically
Traditional approach: CSS frameworks that break every major version Semantic approach: Versioned semantics that never break
Traditional approach: Manual context handling everywhere Semantic approach: Context-aware by default, no code needed
Traditional approach: Notifications spam users regardless of context Semantic approach: Components negotiate attention based on priority and context
Real-World Impact
Accessibility: Free. Every component is screen-reader optimized, keyboard navigable, focus visible.
Responsive: Free. Components adapt to touch, mouse, voice automatically.
Performance: Free. Attention budget prevents cognitive overload.
Privacy: Free. Sensitive content auto-hides in multi-viewer contexts.
Future-proof: Free. Semantic versioning means your code works forever.
This is what the web should have been.
License
MIT License - Use freely in any project
Contributing
This is a proof-of-concept implementation of interaction semantics for the web. Feedback, issues, and contributions welcome.
Built with intent. Designed for humans. Works everywhere.