Ritual dapp design

Skill ritual-foundation/ritual-dapp-skills/skills/ritual-dapp-design

Ritual dApp design system — dark-mode-first color tokens, typography, Tailwind config, async lifecycle state visuals, precompile icons, and AI slop prevention. Use when styling a Ritual Chain frontend, building React/Next.js UI components, implementing async precompile status indicators, or reviewing dApp visual design for brand consistency.From its SKILL.md

Install

npx -y skills add ritual-foundation/ritual-dapp-skills --skill ritual-dapp-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

17.5 KB, as published. Nobody here has run it

Ritual dApp Design System

Design tokens and visual direction for Ritual Chain dApp frontends. Dark-mode-first, technically precise, and unmistakably Ritual.

How to Use This Skill

When styling a new Ritual dApp frontend:

Copy the Tailwind tokens (Section 4) into your tailwind.config.ts.
Set CSS custom properties for fonts (Section 3).
Apply component class patterns (Section 5) to your UI elements.
Map async precompile states to the 9-state lifecycle visuals (Section 6).
Use the precompile icon table (Section 7) for any precompile selector or status display.
Before shipping, run the AI slop self-check (Section 8) against your output.

When reviewing an existing dApp:

Check the color palette against Section 2 — are semantic meanings preserved?
Run the AI slop checklist (Section 8) to flag generic AI-generated patterns.
Verify accessibility (Section 9) — especially gray-500 on elevated surfaces (fails WCAG AA).

Common edge cases:

Izoard is a licensed font. If you don't have it, substitute Archivo Black from Google Fonts.
gray-500 text on bg-ritual-elevated fails WCAG AA (3.7:1 ratio). Use gray-400 minimum.
The 9-state lifecycle covers all async precompiles, but synchronous precompiles (ONNX, Ed25519, JQ) don't have lifecycle states — they return in the same block.

1. Design Philosophy

Core Principles

Precision over decoration. Every element earns its pixels. No ornament that doesn't communicate state, identity, or hierarchy. A green glow means TEE-verified. A pink border means AI-generated. If an element has no semantic reason to exist, remove it.
Atmosphere over brightness. The dark canvas is not a concession to dark mode — it is the medium. Glows, mesh gradients, and noise grain create depth and dimension that only work on black. Light is used surgically: to draw attention, to signal state, to reward completion.
Semantic honesty. Colors, shapes, and motion always mean what they mean. Green never decorates — it certifies. Gold never highlights — it warns. Pink never accents arbitrarily — it marks machine intelligence. Users learn to read the interface once and trust it forever.

What Ritual Is NOT

Not a generic DeFi dashboard (no candy gradients)
Not a Web2 SaaS (no rounded-everything pastel cards)
Not cyberpunk (no neon-on-neon chaos)
Not minimal to the point of sterile (has texture, has atmosphere)

2. Color Palette

Backgrounds

Token	Hex	Usage
`bg-primary`	`#000000`	Page background, base layer
`bg-elevated`	`#111827`	Cards, modals, elevated surfaces
`bg-surface`	`#1F2937`	Input fields, dropdown menus
`bg-overlay`	`rgba(0,0,0,0.8)`	Modal overlays, sheet backgrounds

Accent Colors

Token	Hex	Usage
`accent-green`	`#19D184`	Primary CTAs, success states, TEE verified, active indicators
`accent-lime`	`#BFFF00`	Highlight text, data emphasis, hover states
`accent-pink`	`#FF1DCE`	AI/agent features, persistent agent UI, creative precompiles
`accent-gold`	`#FACC15`	Warnings, pending states, fee displays
`accent-red`	`#EF4444`	Errors, failed states, destructive actions

Grays

Token	Hex	Usage
`gray-700`	`#374151`	Borders, dividers
`gray-500`	`#6B7280`	Secondary text, labels
`gray-400`	`#9CA3AF`	Body text (on dark backgrounds)
`gray-300`	`#D1D5DB`	Primary text headings
`gray-100`	`#F3F4F6`	High-emphasis text (use sparingly)

Color Rules

Green = trust. Use accent-green for anything verified, successful, or connected.
Pink = AI. Any precompile output, agent action, or generated content gets pink accents.
Lime = data. Highlighted numbers, key metrics, and interactive data points.
Gold = caution. Pending operations, fee warnings, lock durations.
Avoid pure white #FFFFFF for backgrounds. Maximum is gray-100 for text.
Prefer green over blue for primary actions. Blue is best reserved for link affordances.

3. Typography

Font Stack

Role	Font	Fallback
Display / Headlines	Izoard	`'Izoard', system-ui, sans-serif`
Body / UI	Barlow	`'Barlow', 'Inter', system-ui, sans-serif`
Code / Data	JetBrains Mono	`'JetBrains Mono', 'Fira Code', monospace`

Note: Izoard is a licensed font from atipo foundry. For open-source projects, substitute with Archivo or Archivo Black (Google Fonts). The key functional requirement: always use a monospace font for hex addresses, data values, and block numbers.

Open-Source Font Alternatives

Role	Licensed	Open-Source Substitute	Google Fonts
Display	Izoard 700	Archivo Black 400 (reads as bold)	Yes
Display (lighter)	Izoard 400	Archivo 600	Yes
Body	Barlow 400/600	Barlow 400/600 (already free)	Yes
Mono	JetBrains Mono	JetBrains Mono (already free)	Yes

Type Scale

Element	Font	Size	Weight	Letter-spacing	Transform
Hero title	Izoard	`4rem` (64px)	700	`-0.02em`	—
Section title	Izoard	`2.5rem` (40px)	700	`-0.01em`	—
Card title	Barlow	`1.25rem` (20px)	600	`0`	—
Body	Barlow	`1rem` (16px)	400	`0`	—
Body small	Barlow	`0.875rem` (14px)	400	`0`	—
Data label	Barlow	`0.75rem` (12px)	500	`0.1em`	`uppercase`
Data value	JetBrains Mono	`0.875rem` (14px)	500	`0`	—
Hex/address	JetBrains Mono	`0.75rem` (12px)	400	`0`	—
Button	Barlow	`0.875rem` (14px)	600	`0.02em`	—

CSS Custom Properties

:root {
  --font-display: 'Izoard', system-ui, sans-serif;
  --font-body: 'Barlow', 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
}

Typographic Rules

Italic: Use only for AI-generated content attribution (e.g., "Generated by claude-sonnet-4-5-20250929") and inline emphasis. Not for body paragraphs.
Long-form body text: max-width: 65ch, line-height: 1.75, Barlow 16px/400.
Fluid display sizes: Use clamp() for hero and section titles to scale without breakpoints: font-size: clamp(2.5rem, 5vw, 4rem).

4. Tailwind Tokens

Extend your Tailwind config with these Ritual-specific tokens:

const config = {
  theme: {
    extend: {
      colors: {
        ritual: {
          black: '#000000', elevated: '#111827', surface: '#1F2937',
          green: '#19D184', lime: '#BFFF00', pink: '#FF1DCE', gold: '#FACC15',
        },
      },
      fontFamily: {
        display: ['var(--font-display)', 'system-ui', 'sans-serif'],
        body: ['var(--font-body)', 'Inter', 'system-ui', 'sans-serif'],
        mono: ['var(--font-mono)', 'Fira Code', 'monospace'],
      },
      boxShadow: {
        'glow-green': '0 0 30px -5px rgba(25, 209, 132, 0.25)',
        'glow-pink': '0 0 30px -5px rgba(255, 29, 206, 0.2)',
        'card': '0 4px 40px -12px rgba(0, 0, 0, 0.5)',
      },
    },
  },
};

5. Component Style Patterns

Class-level patterns. Build your own components around these tokens.

Element	Recommended Classes
Page background	`bg-black min-h-screen text-gray-300 font-body`
Card	`bg-ritual-elevated border border-gray-800 rounded-xl shadow-card p-6`
Primary button	`border border-ritual-green text-ritual-green hover:bg-ritual-green/10 px-4 py-2.5 rounded-lg font-semibold`
Secondary button	`border border-dashed border-ritual-gold text-ritual-gold hover:bg-ritual-gold/10`
Ghost button	`border border-gray-700 text-gray-400 hover:border-gray-600`
Danger button	`border border-red-500/50 text-red-400 hover:bg-red-500/10`
Text input	`bg-ritual-surface border border-gray-700 rounded-lg px-4 py-3 text-sm text-gray-300`
Data label	`text-xs text-gray-500 uppercase tracking-wider`
Data value	`text-sm text-gray-300 font-mono`
Hex address	`font-mono text-xs text-gray-500` (truncate to `0x1234...5678`)
Section divider	`h-px bg-gradient-to-r from-ritual-green/30 via-gray-800 to-transparent`
Focus ring	`focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ritual-green/50 focus-visible:ring-offset-2 focus-visible:ring-offset-black`

Ritual buttons are transparent with borders, not filled. The primary button is a green-bordered outline that glows on hover — filled buttons feel consumer/SaaS, outlines feel technical/crypto-native. Use rounded-xl max; mix with sharper corners where appropriate.

6. Async Lifecycle States

Every async precompile operation passes through up to 9 states. Each state has a distinct visual treatment. Always pair color with an icon and text label — never rely on color alone (see Accessibility).

State	Dot Color	Animated	Text Color	Icon
Submitting	gray	pulse	`text-gray-400`	`·`
Awaiting Executor	gold	pulse	`text-ritual-gold`	`◌`
Committed	gold	static	`text-ritual-gold`	`◉`
Processing	green	pulse	`text-ritual-green`	`⟳`
Result Ready	green	static	`text-ritual-green`	`◈`
Settling	gold	static	`text-ritual-gold`	`◎`
Settled	green	static	`text-ritual-green`	`✓`
Failed	red	static	`text-red-400`	`✗`
Expired	gray-600	none	`text-gray-500`	`⊘`

7. Ritual Visual Language

Precompile Type Icons

Each precompile type has a geometric icon. Green = data operations, pink = AI/inference, lime = cryptographic, gold = scheduling.

Type	Address	Icon	Color
ONNX	`0x0800`	`⬡`	green
HTTP	`0x0801`	`⇄`	green
LLM	`0x0802`	`◇`	pink
JQ	`0x0803`	`{}`	green
Long HTTP	`0x0805`	`⟳`	green
ZK Long-Running	`0x0806`	`△`	lime
FHE	`0x0807`	`◈`	lime
Sovereign Agent	`0x080C`	`▣`	pink
Image	`0x0818`	`◐`	pink
Audio	`0x0819`	`♫`	pink
Video	`0x081A`	`▶`	pink
Persistent Agent	`0x0820`	`⊞`	pink

TEE Verification Badge

A green badge with "TEE Verified" text signals enclave-computed results. Style: bg-ritual-green/10 text-ritual-green border border-ritual-green/20. Include a small geometric icon (rotated square suggesting a hexagon) for visual weight.

AI Output Treatment

Any content produced by an AI precompile (LLM, Agent, Image, etc.) should be visually distinguished with a pink top-border gradient (border-ritual-pink/20), a diamond icon ◇ with "AI Output" label, and the model name in gray monospace.

Scheduler Badge

Transactions from the system scheduler (sender 0x000...fa7e, type 0x10) should show a gold ⏲ Scheduled badge to distinguish them from user-initiated calls.

spcCalls Receipt Display

Ritual transaction receipts include an spcCalls array (precompile input/output pairs inline). Display these as collapsible monospace blocks with a "Decode" action.

Encrypted Content

ECIES-encrypted results should show a blurred placeholder with a lock icon and "Decrypt" button. Only the user's key can read the content.

8. AI Slop Detection Checklist

Before shipping any Ritual dApp UI, audit against these signals of generic AI-generated design:

Red Flag	Why It's Wrong	Fix
Purple/violet gradients	Default AI color scheme, screams "ChatGPT made this"	Use Ritual's green/lime/pink accents on black
System fonts (Inter everywhere)	No brand identity	Use Izoard for display, Barlow for body
Perfectly symmetric grid layouts	Feels templated, no visual tension	Break one column wider, offset elements
Generic gray `#f5f5f5` backgrounds	Web2 SaaS energy	Pure black `#000000` with `#111827` cards
`box-shadow: 0 2px 8px rgba(0,0,0,0.1)`	The default AI shadow	Use dramatic `shadow-card` or glow variants
Rounded-2xl on everything	Friendly/consumer, not crypto-native	Mix sharp corners with selective rounding
Blue primary buttons	Every AI default	Green border buttons with glow
Stock gradient hero sections	Immediately recognizable as AI	Mesh gradients with noise texture
`backdrop-blur-xl` everywhere	Overused glassmorphism	One blur layer max, for overlays only
Rainbow/multicolor schemes	No focus, no brand	Disciplined 3-color maximum per screen
Centered everything	No visual hierarchy	Left-align text, use asymmetric layouts
`animate-bounce` on CTAs	Annoying, unprofessional	Subtle `pulse-green` glow or no animation

Self-Check Protocol

Before generating any UI component, check your output for these patterns and replace with the Ritual equivalent:

Pattern to Detect	Replacement
`Inter` or `Roboto` as display font	`var(--font-display)` (Izoard / Archivo)
`#6366f1` or `#3b82f6` (indigo/blue)	`#19D184` (ritual-green) or `#FF1DCE` (ritual-pink)
`bg-white` or `bg-gray-50`	`bg-black` (page) or `bg-ritual-elevated` (card)
`shadow-md` or `shadow-lg`	`shadow-card` or `shadow-glow-green`
`rounded-2xl` or `rounded-3xl`	`rounded-xl` max
`animate-bounce`	`animate-pulse-green` or remove
`bg-blue-500 text-white` button	`border border-ritual-green text-ritual-green`

9. Accessibility

Color Contrast Audit

Foreground	Background	Ratio	WCAG AA (4.5:1)
gray-300 (`#D1D5DB`)	black (`#000000`)	13.8:1	Pass
gray-400 (`#9CA3AF`)	black (`#000000`)	8.3:1	Pass
gray-500 (`#6B7280`)	black (`#000000`)	4.6:1	Pass
green (`#19D184`)	black (`#000000`)	7.5:1	Pass
green (`#19D184`)	elevated (`#111827`)	6.0:1	Pass
pink (`#FF1DCE`)	elevated (`#111827`)	4.6:1	Pass
red (`#EF4444`)	black (`#000000`)	4.6:1	Pass
gray-500 (`#6B7280`)	elevated (`#111827`)	3.7:1	Fail

Key finding: gray-500 on bg-ritual-elevated fails WCAG AA. Use gray-400 (#9CA3AF) minimum for any text on elevated surfaces.

Colorblind Safety

Green and red are the primary success/error pair. For red-green colorblind users (~8% of males), never rely on color alone:

State	Color	Required Non-Color Signal
Success	Green	Checkmark icon (✓) + "Success" text
Error	Red	X icon (✗) + "Failed" text + shake animation
Pending	Gold	Clock icon (◌) + "Pending" text + pulse
AI output	Pink	Diamond icon (◇) + "AI Output" label

ARIA Patterns

Component	Required ARIA
Status indicators	`role="status"` + `aria-label="Job status: {text}"`
Progress bars	`role="progressbar"` + `aria-valuenow` + `aria-valuemax`
Streaming text	`role="log"` + `aria-live="polite"`
Toasts	`role="alert"`
Modals	`role="dialog"` + `aria-modal="true"` + `aria-label="{title}"`

Additional Requirements

Focus ring on all interactive elements: focus-visible:ring-2 focus-visible:ring-ritual-green/50 focus-visible:ring-offset-2 focus-visible:ring-offset-black
Reduced motion: Wrap animations in @media (prefers-reduced-motion: reduce) or use Framer Motion's useReducedMotion.
Touch targets: 44x44px minimum on mobile for all interactive elements.
Semantic HTML: Use <main>, <nav>, <table>, <dialog> — not divs for everything.
Skip navigation: Add a visually-hidden skip link at the top of every page.

10. Responsive Design

Breakpoint	Width	Behavior
`sm`	640px	Stack to single column, reduce padding
`md`	768px	Sidebar moves below main content
`lg`	1024px	Two-column layout activates
`xl`	1280px	Maximum content width

Transaction status cards stack vertically and become full-width on mobile.
Hex addresses always truncate to 0x1234...5678.
Toast notifications anchor to bottom-center on mobile, bottom-right on desktop.
Font sizes use fluid clamp() — see Typography section.
Buttons become full-width on mobile (w-full sm:w-auto).

Quick Reference

Concept	Value
Page background	`bg-black` (`#000000`)
Card background	`bg-ritual-elevated` (`#111827`)
Primary accent	`ritual-green` (`#19D184`) — trust, success
AI accent	`ritual-pink` (`#FF1DCE`) — agent/generated
Warning accent	`ritual-gold` (`#FACC15`) — pending, fees
Data accent	`ritual-lime` (`#BFFF00`) — metrics, emphasis
Display font	Izoard (licensed) / Archivo Black (open-source)
Body font	Barlow (free)
Mono font	JetBrains Mono (free)
Chain ID	1979
Scheduler system sender	`0x000...fa7e` (type `0x10`)
Button style	Transparent + colored border + glow on hover
Max rounding	`rounded-xl` — mix with sharper corners
Min text on elevated	`gray-400` (`#9CA3AF`) for WCAG AA compliance