modus-frontend

This skill guides creation of production-grade frontend interfaces using the Modus 2.0 Design System. All output must strictly follow the design system constraints below. The result should be polished, professional, enterprise-grade UI that is fully theme-compatible and design-system compliant.

The user provides frontend requirements: a component, page, dashboard, or interface to build. They may include context about the purpose, audience, or technical constraints.

Design Thinking

Before coding, understand the context:

• •Purpose: What problem does this interface solve? Who uses it? (field workers, office managers, engineers, administrators)
• •Layout: What layout pattern fits? (sidebar + content, top nav + grid, full-width dashboard, split pane, card grid)
• •Information hierarchy: What's most important? Use font size scale, color weight, and spacing to guide the eye.
• •Theme compatibility: Will this look correct in both light and dark themes? Never hardcode colors.

The Modus design system philosophy is clean, consistent, and professional. Express creativity through thoughtful layout composition, smart use of the 9-color system with opacity variants, precise spacing, and clear visual hierarchy - not through custom fonts, wild color palettes, or decorative flourishes.

9-Color Semantic System

ALL colors must come from these 9 semantic tokens. No exceptions.

Base Colors (5)

Status Colors (4)

Foreground Variants

Each color has a -foreground variant for text placed on top of that color:

• •text-primary-foreground (text on bg-primary)
• •text-card-foreground (text on bg-card)
• •text-muted-foreground (subdued text)
• •text-secondary-foreground (text on bg-secondary)

Opacity Variants

Each color supports 4 opacity levels: -80, -60, -40, -20

text-foreground-80    bg-primary-20    border-warning-60
text-muted-foreground-60    bg-destructive-40    bg-success-20

CRITICAL: Use text-foreground-80 NOT text-foreground/80. The Tailwind / opacity syntax does not work with CSS variables.

Additional Utility Tokens

Typography

Font: Open Sans is the only permitted font. It is loaded globally by the design system.

Font Scale (Modus scale):

Font Weights: font-normal (400), font-medium (500), font-semibold (600), font-bold (700)

Tailwind CSS Usage

Use Tailwind utility classes for layout, spacing, and sizing. Colors MUST come exclusively from the design system.

Correct usage:

bg-background text-foreground p-4 rounded-lg flex gap-3
bg-card text-card-foreground border-default shadow-sm
bg-primary text-primary-foreground px-4 py-2 rounded-md
text-muted-foreground-60 text-sm

NEVER use:

bg-blue-500      (generic Tailwind color)
text-gray-600    (generic Tailwind color)
bg-[#1a2b3c]    (hardcoded hex)
text-[rgb(...)]  (hardcoded RGB)
bg-slate-100     (any named Tailwind palette)

Border Utilities

Borders use custom utility classes that work correctly with CSS variables. Do NOT combine Tailwind border utilities with design system colors.

Default Borders

border-default           1px solid border color
border-thick             2px solid border color
border-dashed            1px dashed border color
border-thick-dashed      2px dashed border color

Directional Borders

border-top-default       border-bottom-default
border-left-default      border-right-default

CRITICAL: Use border-bottom-default NOT border-b border-default. The combined pattern breaks with CSS variables.

Status Borders

Each status color has full border variants:

border-primary           border-thick-primary       border-dashed-primary
border-success           border-thick-success       border-dashed-success
border-warning           border-thick-warning       border-dashed-warning
border-destructive       border-thick-destructive   border-dashed-destructive

Plus directional variants: border-top-primary, border-bottom-success, border-left-warning, border-right-destructive, etc.

Icons

Use Modus Icons exclusively. The library includes 700+ icons in 3 variants.

Usage:

<i class="modus-icons">notifications</i>
<i class="modus-icons">settings</i>
<i class="modus-icons">check_circle</i>
<i class="modus-icons">warning_outline</i>

Variants (via wrapper component or CSS class):

• •Regular (default): line-style icons
• •Solid: modus-icons-solid - filled icons
• •Outlined: modus-icons-outlined - outlined icons

Size: Default 24px. Adjust with Tailwind text-[size] on the <i> element or wrapper component props.

NEVER use: Font Awesome, Material Icons, Heroicons, Lucide, Phosphor, or any other icon library.

Component Library

Modus Web Components provide all UI primitives. Use the framework's wrapper components (not raw web component tags).

Available components include:

• •Layout: Card, Accordion, Tabs, Modal, Side Navigation, Navbar, Utility Panel
• •Forms: Button, Checkbox, Radio, Switch, Text Input, Number Input, Select/Dropdown Menu, Date Picker, Time Picker, File Upload
• •Data: Table, Data Table, Pagination, Badge, Chip, Progress Bar, Spinner
• •Feedback: Alert, Toast, Tooltip, Message
• •Navigation: Breadcrumbs, Menu, Side Navigation, Tabs
• •Media: Autocomplete, Slider, Sentiment Scale

Key patterns:

• •Use ModusDropdownMenu instead of ModusSelect for reliable event handling
• •Let Modus components manage their own internal state (e.g., accordion expand/collapse)
• •Use slot-based composition for cards (header, default content, footer slots)
• •Modals use dialog-based patterns (showModal()/close())

Checkbox value bug: The value property from checkbox inputChange events is inverted. Always invert:

const actualChecked = !event.detail.value;

Theme Support

The design system supports 6 themes via the data-theme attribute on <html>:

All semantic color variables automatically update when the theme changes. This means:

• •Never hardcode colors - always use the semantic tokens
• •Test mental model in both light and dark: bg-card is light in light themes, dark in dark themes
• •Use opacity variants for subtle layering that works across themes (bg-primary-20, text-foreground-60)

HTML Elements

Use <div> elements for all layout and content containers. Avoid semantic HTML elements (h1, h2, p, section, article, span, header, footer, nav, main) as they can conflict with Tailwind CSS and Modus web component styling.

Exception: <i> elements are used for Modus Icons.

Apply text styling via Tailwind classes on <div> elements:

<div class="text-3xl font-bold text-foreground">Page Title</div>
<div class="text-base text-muted-foreground">Body text content</div>
<div class="text-sm text-foreground-60">Secondary information</div>

Animations

Use CSS animations sparingly for professional transitions:

/* Fade in */
@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

/* Slide in from right */
@keyframes slide-in-right {
  from { transform: translateX(100%); }
  to { transform: translateX(0); }
}

Utility classes: animate-fade-in, animate-slide-in-right

Tailwind transition utilities work well: transition-all duration-200 ease-out

Focus on functional transitions (panel open/close, content loading) rather than decorative motion.

Strict Prohibitions

• •No emojis in code or UI text
• •No generic Tailwind colors (blue-500, gray-300, slate-100, etc.)
• •No hardcoded hex, RGB, HSL, or named CSS colors
• •No external icon libraries (Font Awesome, Material Icons, Heroicons, etc.)
• •No custom fonts or Google Fonts imports (Open Sans is provided by the design system)
• •No border-b border-default pattern (use border-bottom-default)
• •No text-foreground/80 opacity syntax (use text-foreground-80)
• •No semantic HTML elements for layout (h1, p, section, span, etc.)
• •No inline styles with hardcoded color values
• •No direct usage of internal --modus-wc-color-* variables (use the semantic tokens)

Design Quality

Within these constraints, produce polished, professional interfaces:

• •Visual hierarchy: Use font scale (text-3xl to text-xs), font weight, and color opacity to establish clear information hierarchy
• •Spacing: Use consistent Tailwind spacing (gap-2, gap-4, gap-6, p-4, p-6) for rhythm. Be generous with whitespace.
• •Card composition: Use bg-card with border-default and rounded-[--radius-card] for content grouping
• •Status communication: Use the 4 status colors purposefully - primary for info/action, success for positive, warning for caution, destructive for errors
• •Layering with opacity: bg-primary-20 for subtle highlights, text-foreground-60 for secondary text, bg-muted for section backgrounds
• •Data visualization: Use --chart-1 through --chart-5 for charts and graphs
• •Responsive layout: Use Tailwind responsive prefixes (sm:, md:, lg:) and flexbox/grid utilities
• •Focus states: Use ring color for focus indicators

Remember: Professional design within a constrained system comes from precision - perfect alignment, consistent spacing, purposeful color application, and clear visual hierarchy. The 9-color system with opacity variants provides more than enough range for expressive, polished UI.