Design System

PolkAudit Visual & Component Guidelines

Back to Home

Brand Foundation

The PolkAudit brand represents trust, transparency, and enterprise reliability in Polkadot governance.

Brand Pillars

Trustworthy

Enterprise-grade security and reliability

Transparent

Clear, honest communication

Professional

Polished, minimal aesthetic

Accessible

Inclusive design for all users

Design Principles

Clarity First

Information should be immediately understandable without cognitive load

Minimal & Focused

Remove unnecessary elements; every visual decision must serve a purpose

Professional Elegance

Enterprise-appropriate design with refined details and careful spacing

Dark Mode Native

Design for dark theme first; optimize for reduced eye strain and fintech aesthetics

Consistent Systems

Use predictable patterns and reusable components across all interfaces

Accessible Always

WCAG AA compliance minimum; consider color contrast, keyboard nav, and screen readers

Brand Voice

Tone & Manner

Professional yet approachable. We avoid hype and unnecessary jargon. We speak with confidence about complex topics while remaining clear and direct.

✓ Do

Be precise and concrete
Use active voice
Explain the benefit, not just feature
Use data to support claims

✗ Don't

Use marketing hype
Assume user knowledge
Over-use exclamation marks
Be unnecessarily technical

Color System

Our color palette is designed for accessibility and enterprise aesthetics. All colors meet WCAG AA contrast ratios.

Palette Overview

Primary Brand

#6d28d9

#7c3aed

Used for primary actions and accents

Neutral Scale

From light to dark neutral tones

Functional Colors

Success

Error

For messaging and feedback

Semantic Color Tokens

Primary

var(--primary)

Interactive elements, CTAs, primary actions

Primary Foreground

var(--primary-foreground)

Text on primary backgrounds

Accent

var(--accent)

Highlights, decorative accents, focus states

Background

var(--background)

Main page background

Foreground

var(--foreground)

Primary text color

Card

var(--card)

Card and container backgrounds

Card Foreground

var(--card-foreground)

Text on card backgrounds

Muted

var(--muted)

Disabled states, secondary elements

Muted Foreground

var(--muted-foreground)

Secondary text, hints

Border

var(--border)

Dividers and borders

Accessibility & Contrast

✓ WCAG AA Compliant

All text/background combinations meet or exceed WCAG AA contrast standards (4.5:1 for normal text)

Example Combinations:

Foreground on Background

Ratio: 13.5:1

Card Foreground on Card

Ratio: 9.2:1

Usage Guidelines

Primary Color (#6d28d9)

Used for primary buttons, links, and important interactive elements. Apply sparingly for maximum impact.

Accent Color (#7c3aed)

Use for hover states, highlights, and decorative accents. Creates visual hierarchy and draws attention to important elements.

Neutral Palette

Build depth and hierarchy with our neutral scale. Use for backgrounds, borders, and secondary content.

Typography

We use a carefully selected typography system that balances readability with enterprise aesthetics.

Font Stack

Heading Font

System UI Fonts

ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI"

Used for all headings and display text for maximum platform consistency.

Body Font

System UI Fonts

Same as headings for consistency across all interfaces.

Optimized for screen reading and long-form content clarity.

Type Scale

Design System

Display / Page Title

32px / 1.2

Weight: bold

text-4xl font-bold

Brand Principles

Heading 1 / Section

28px / 1.3

Weight: 600

text-3xl font-semibold

Color Palette

Heading 2 / Subsection

24px / 1.3

Weight: 600

text-2xl font-semibold

Typography Scale

Heading 3

20px / 1.4

Weight: 600

text-xl font-semibold

Regular paragraph text for reading

Body / Default

16px / 1.5

Weight: 400

text-base

Supporting text and descriptions

Small / Secondary

14px / 1.5

Weight: 400

text-sm

Labels, hints, and metadata

Caption / Label

12px / 1.4

Weight: 500

text-xs

Line Height & Spacing

Line Height Standards

• Headings: 1.2 (tight, confident)

• Body: 1.5 (relaxed, readable)

• Captions: 1.4 (compact)

Provides comfortable reading rhythm while maintaining visual hierarchy.

Letter Spacing

• Default: Normal (0)

• Display: Slightly tighter

• Uppercase: +0.05em (slight expansion)

Maintains readability across all sizes and styles.

Font Weights

Bold (700)

Headings, emphasis, important labels

Semibold (600)

Subheadings, strong emphasis, button text

Regular (400)

Body text, default content

Medium (500)

Labels, secondary headings, emphasis in body

Practical Examples

Page Title

Audit Governance Dashboard

Card Heading

Key Metrics

This is example body text that sits under a card heading. It uses a 16px size with 1.5 line-height for comfortable reading and visual hierarchy.

Button & Label

Inline help text with smaller font size

Guidelines

Best Practices

✓ Use text-balance on titles for better line breaks
✓ Maintain consistent line-height within content blocks
✓ Limit font size variations to improve visual coherence
✓ Use semantic weight hierarchy: Bold > Semibold > Regular
✓ Never go below 14px for body text on desktop

Spacing & Layout

Our layout system uses an 8px base grid for consistent, predictable spacing throughout the interface.

8px Base Grid

All spacing values are multiples of 8px for visual harmony:

p-0

0px

No spacing

p-1

0.25rem (4px)

Minimal spacing, icon offsets

p-2

0.5rem (8px)

Tight spacing, component padding

p-3

0.75rem (12px)

Small spacing, input fields

p-4

1rem (16px)

Default spacing, padding, gaps

p-6

1.5rem (24px)

Section spacing, card padding

p-8

2rem (32px)

Large spacing, major sections

p-12

3rem (48px)

Extra large spacing, page sections

Responsive Breakpoints

Mobile

base

Full width

Small

640px

Medium

768px

Large

1024px

Extra Large

1280px

2XL

2xl

1536px

Mobile-First Approach

Design for mobile first, then enhance with md:, lg:, xl: prefixes for larger screens

Container Sizes

max-w-sm

Narrow sidebars, small cards

384px

max-w-md

Forms, dialogs

448px

max-w-lg

Content areas, modals

512px

max-w-2xl

Standard content

672px

max-w-4xl

Design system (this page)

896px

max-w-6xl

Full page content

1152px

Layout Patterns

Flex for Most Layouts

flex-1

Use flexbox (flex, gap, items-center, justify-between) for responsive layouts

Grid for Complex 2D Layouts

Use CSS Grid (grid-cols-3, gap-4) for multi-column layouts

Stack Vertically (Flex Column)

Use space-y-* classes or flex flex-col for vertical stacking

Padding & Margin Usage

Internal Spacing (Padding)

• Buttons: p-2 to p-3
• Inputs: p-2 to p-3
• Cards: p-4 to p-6
• Sections: p-6 to p-8

External Spacing (Margin)

• Between sections: my-12 to my-16
• Between elements: mb-4 to mb-6
• Gap between items: gap-4
• Never use margin on components

Safe Area & Page Margins

max-w-4xl mx-auto (page container)

px-4 sm:px-6 lg:px-8 (horizontal padding)

Provides consistent margins at all screen sizes and prevents content from touching screen edges on mobile

Layout Best Practices

✓ Use space-y-* and gap classes instead of margin on child elements
✓ Stick to 8px multiples for all spacing (4, 8, 12, 16, 24, 32, 48, 64...)
✓ Always use responsive padding: px-4 sm:px-6 lg:px-8
✓ Prefer flex for alignment, grid for complex multi-column layouts
✓ Never nest containers without considering the full layout chain

UI Components

Reusable component patterns built with shadcn/ui principles. All components are accessible and follow our design system.

Buttons

Primary Button

bg-primary text-primary-foreground

Secondary Button

border border-border hover:bg-card

Tertiary Button

text-foreground hover:bg-secondary

Disabled Button

bg-muted text-muted-foreground disabled

Cards

CARD LABEL

Card Title

Card content with supporting description text

FEATURE

Metric description goes here

Input Fields

Text Input

Email Input

Select Field

Badges & Labels

PrimaryAccentMutedOutlinedSuccessError

Alert States

Success

Operation completed successfully

Info

Here's some helpful information

Warning

Please be careful with this action

Error

Something went wrong

Accordion Pattern

PolkAudit provides transparent governance tracking and treasury auditing for Polkadot teams.

Dividers

Simple Border

With Label

Component Guidelines

✓ Always use semantic colors (primary, accent, muted) instead of hard-coded values
✓ Include proper focus states and keyboard navigation for accessibility
✓ Use consistent padding and border-radius across similar components
✓ Test contrast ratios meet WCAG AA minimums
✓ Consider hover, focus, and active states for interactive elements

Data Visualization Style

Guidelines for displaying data, metrics, and charts in PolkAudit interfaces.

Metric Cards

Total Audits

1,247

↑ 12% this month

Completion Rate

94%

↓ 2% vs last month

Avg Response

2.3h

↑ Faster than usual

Active Users

542

Across all teams

Chart Styles

Line Chart

Use accent color with gradient for visual interest

Progress Indicators

Complete75%

In Progress45%

Pie / Donut Chart

Use accent colors for segments

Status List

Active - 234

Pending - 89

Failed - 12

Data Tables

Audit ID	Status	Date
#AU-001	Completed	2024-07-15
#AU-002	In Progress	2024-07-15
#AU-003	Pending	2024-07-15

Icons & Indicators

→

Trend Up

↓

Trend Down

✓

Success

Error

Color Palette for Charts

Sequential (Use for single series):

Light to dark purple progression

Categorical (Use for multiple series):

Distinct colors for multiple data series

Data Visualization Best Practices

✓ Use accent and primary colors for highlights and main data
✓ Keep charts minimal and focused - remove chartjunk
✓ Include units and labels for clarity
✓ Show comparison or trend context when possible
✓ Use consistent color mapping across all visualizations
✓ Ensure contrast is sufficient for all data points

Motion & Transitions

Subtle, purposeful animations that enhance usability without distraction.

Motion Principles

Purpose First

Every animation should serve a purpose: provide feedback, guide attention, or smooth state changes.

Keep It Fast

Animations should be 200-500ms. Faster feels instantaneous, slower feels sluggish.

Subtle & Refined

Avoid obvious or exaggerated animations. Movement should be smooth and sophisticated.

Respect Preferences

Always respect prefers-reduced-motion for accessibility.

Common Transitions

Button Hover

transition-all (color + scale)

Button Active

active:scale-95

Fade In

opacity: 0 → 1 (300ms)

Slide In

transform: translateX (300ms)

Scale (Focus)

scale: 1 → 1.1 (200ms)

Color Transition

transition-colors (200ms)

Timing Guidelines

150msQuick feedback (hover, focus)

200msColor & opacity changes

300msSlide, scale, fade animations

500msComplex transitions, page layouts

1000ms+Loading states, long operations

Easing Functions

ease-in-outDefault, natural feeling

ease-outQuick start, smooth end - for show/hide

ease-inSlow start, quick end - less common

linearConstant speed - use sparingly

Common CSS Patterns

Button Hover State

className="...
  hover:bg-primary/90
  transition-colors
  duration-200"

Active State with Scale

className="...
  active:scale-95
  transition-transform
  duration-150"

Focus State

className="...
  focus:outline-none
  focus:ring-2
  focus:ring-accent
  transition-all"

Respecting Motion Preferences

Always respect the prefers-reduced-motion setting:

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

Motion Best Practices

✓ Use transitions-all for hover/focus states
✓ Keep animations under 500ms except for special cases
✓ Use ease-in-out for most animations (feels natural)
✓ Add transition-colors for color changes only
✓ Use transform (scale, translateX) instead of width/height (better performance)
✓ Always test with prefers-reduced-motion enabled

Voice & Copy Style

Guidelines for writing copy that resonates with our enterprise audience while remaining clear and actionable.

Tone Attributes

Professional

We speak with expertise and authority

Clear

We explain complex topics simply

Direct

We get to the point without jargon

Honest

We avoid marketing hype and exaggeration

Helpful

We prioritize user success

Confident

We trust our product and expertise

Writing Principles

Use Active Voice

✓ Do

Export audit reports in seconds

✗ Don't

Audit reports can be exported quickly

Be Specific & Concrete

✓ Do

Track changes across 50+ governance parameters

✗ Don't

Monitor comprehensive governance data

Show the Benefit

✓ Do

Save 10 hours of manual audit work per report

✗ Don't

Automated audit report generation

Avoid Marketing Speak

✓ Do

Enterprise-grade security with encryption

✗ Don't

Industry-leading next-gen security solutions

Use Conversational Language

✓ Do

We help you track governance changes

✗ Don't

PolkAudit facilitates governance monitoring

Copy Examples

Hero Headline

Track governance. Prove compliance. Scale confidently.

Benefits-focused, action-oriented, punchy

Subheading / Value Prop

Live finalized block indexing with comprehensive governance extraction

Specific, technical, supports the main message

Call-to-Action Button

Action-driven, benefit-focused, specific outcome

Error Message

Export failed: Please check your permissions and try again

Specific problem, actionable next step, empathetic tone

Help Text / Hint

We'll email you the audit report within 24 hours

Clarifies what to expect, reduces uncertainty

Common UI Copy Patterns

Navigation

Dashboard, Audits, Reports, Settings

Primary Button

Start Audit, Export Report, Save Changes

Secondary Button

Cancel, Go Back, Learn More

Confirmation

Are you sure? This action can't be undone.

Empty State

No audits yet. Create your first audit to get started.

Indexing blocks... This may take a few minutes.

Success

Audit exported successfully. Check your email.

Preferred Terminology

Use	Instead of	Why
Audit	Scan, Analysis	Our core service
Export	Download, Generate	More precise action
Track	Monitor, Watch	Active, engaged tone
Team	Organization, Account	Familiar, human
Treasury	Budget, Funds	Precise terminology
Governance	Parameters, Settings	Specific domain

Copywriting Best Practices

✓ Use active voice and concrete verbs
✓ Show benefits before features
✓ Keep sentences short and scannable
✓ Use second person ("you") in CTAs
✓ Be specific with numbers and details
✓ Avoid jargon unless your audience expects it
✓ Test copy for clarity and tone consistency

Tailwind Tokens & Reference

Complete reference for all Tailwind CSS tokens and utilities used in the PolkAudit design system.

Quick Reference

Semantic Color Variables

--background: #0a0e27;
--foreground: #e8eaef;
--card: #14192e;
--primary: #6d28d9;
--accent: #7c3aed;
--muted: #374151;
--border: #1e293b;

Spacing Scale

p-0, p-1 (4px), p-2 (8px), p-3 (12px)
p-4 (16px), p-6 (24px), p-8 (32px)
p-12 (48px), p-16 (64px)

Typography Scale

text-xs (12px)    - Captions
text-sm (14px)    - Small text
text-base (16px)  - Body text
text-lg (20px)    - Headings
text-2xl (24px)   - Section title
text-3xl (28px)   - Major section
text-4xl (32px)   - Page title

Border & Rounded

rounded-none   (0px)
rounded-sm     (2px)
rounded        (4px)
rounded-md     (6px)
rounded-lg     (8px)
rounded-full   (9999px)

Color Tokens

Token	Variable	Usage	Example
bg-background	--background	Page backgrounds	Sample
text-foreground	--foreground	Primary text	Sample
bg-card	--card	Card backgrounds	Sample
bg-primary	--primary	Primary actions	Sample
bg-accent	--accent	Highlights	Sample
text-muted	--muted	Disabled states	Sample
border-border	--border	Dividers	Sample

Responsive Utilities

sm:

@media (min-width: 640px)

sm:px-6 sm:grid-cols-2

md:

@media (min-width: 768px)

md:text-xl md:w-1/2

lg:

@media (min-width: 1024px)

lg:px-8 lg:grid-cols-3

xl:

@media (min-width: 1280px)

xl:grid-cols-4

Common Tailwind Patterns

Page Container

max-w-4xl mx-auto px-4 sm:px-6 lg:px-8

Flex Center

flex items-center justify-center

Flex Between

flex items-center justify-between

Grid 3 Column

grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4

Card with Hover

p-6 rounded-lg bg-card border border-border hover:border-accent transition-colors

Button Base

px-4 py-2 rounded-lg font-semibold text-sm transition-colors

Text Balance

text-balance text-lg font-semibold text-foreground

Focus Ring

focus:outline-none focus:ring-2 focus:ring-accent

Spacing Scale Reference

p-0

p-1

4px

p-2

8px

p-3

12px

p-4

16px

p-6

24px

p-8

32px

p-12

48px

p-16

64px

p-20

80px

p-24

96px

p-32

128px

Transition Utilities

transition-colors

transition-all

transition-opacity

transition-transform

duration-150

duration-200

duration-300

ease-in-out

hover:bg-secondary

active:scale-95

focus:ring-2

Accessibility Utilities

sr-only

Screen reader only text - hidden visually

focus:ring-2

Visible focus indicator for keyboard navigation

focus:outline-none

Remove default browser outline when using custom ring

aria-label=""

Provide accessible names for icon buttons

Tailwind Best Practices

✓ Use semantic color tokens (primary, accent, muted) not hard-coded hex values
✓ Always include responsive prefixes: sm:, md:, lg: for all utilities
✓ Prefer gap and space-y classes over individual margins
✓ Use max-w and mx-auto for consistent container sizing
✓ Apply transitions for all interactive state changes
✓ Always include focus states and keyboard navigation utilities
✓ Use opacity modifiers (opacity-50, opacity-75) instead of arbitrary colors

Resources

• Tailwind CSS docs: tailwindcss.com
• Our globals.css: Defines all custom color tokens
• shadcn/ui: Pre-built components using these tokens