Design Guidelines
The official standards for creating consistent interfaces.
Core Visual Identity
Color Palette
Our primary UI color is a warm terracotta/copper (hue ~39). Neutral colors map exclusively to warm stone grays. Semantic colors (success, warning, error, info) communicate system state.
Light Mode
Dark Mode
Typography
Our typographic scale is designed for readability and clear hierarchy, utilizing three primary font families:
- UI & Content: PT Sans (Sans-serif)
- Headings & Prose: PT Serif (Serif)
- Data & Code: Fira Code (Monospace)
Base font size is 16px with a 1.5 line height. Headings should be strictly bold (700 or 800 weight).
Implementation Ready
Need to apply these brand colors and fonts to your Nuxt or Tailwind project? Grab the ready-to-use theme tokens and configuration files.
Design System & Best Practices
These guidelines are base recommendations for consistency and predictability. You can use custom styling for application-specific requirements.
Layout & Structural Foundations
Spacing Scale
All layouts use the 4px/8px grid system (Tailwind's default). Maintain visual rhythm by using consistent even-numbered gaps like gap-4 (16px) or gap-6 (24px) for component spacing. This 4px multiplier strictly applies to internal padding (p-*) and external margins (m-*) as well. Avoid odd numbers.
Z-Index Hierarchy
The following standardized z-index scale is strictly enforced to prevent overlapping components and visual bugs:
z-40Dropdownsz-50Sticky Headersz-[100]Modalsz-[200]Toasts
Max Widths
Use the following standardized container widths based on the content context:
- Prose/Reading Use
max-w-3xlto maintain an optimal reading line length. - Dashboards Use
max-w-7xlor full fluid width for dense data tables and metrics.
Border Radii
Utilize a constrained border-radius scale to maintain a professional yet approachable aesthetic. With Nuxt UI configuration, the global default is 0.2rem via the --ui-radius variable. Ensure consistency across cards, inputs, and modals.
Shadows & Elevations
Depth is established using custom, softer tweaked shadows (low opacity, diffuse spread) to dictate the z-axis hierarchy. Use shadow-sm for standard cards, shadow-md for dropdowns and popovers, and shadow-xl for blocking overlays like modals.
Buttons & Call to Actions (CTAs)
Primary vs. Secondary Actions
Establish a clear visual hierarchy by restricting interfaces to a single primary action per view or form. Use the solid primary variant to draw focus to the main objective, and relegate all alternative actions to outline or soft secondary variants.
The Ghost Variant
Utilize the ghost variant for actions of low importance, such as "Cancel", "Back", or "Skip". This reduces visual clutter while ensuring the action remains accessible without competing with primary or secondary objectives.
Split Buttons & Dropdowns
Use split buttons when you have more than two related tasks. They keep the primary action instantly accessible, while grouping alternatives in a dropdown. The main button triggers the default action (e.g., “Save”), and the chevron opens less common options.
Icons within Buttons
Enhance button scannability by including a leading or trailing icon, but avoid overusing them. When using a standalone icon button without a label, always pair it with a tooltip and an aria-label for accessibility.
Display & Navigation Patterns
Modals vs. Slide-overs
Use modals exclusively for quick confirmations or simple inputs that block the immediate flow. Use slide-overs (drawers) for complex forms, deep detail views, or tasks that require referencing data from the underlying background page.
Pagination vs. Infinite Scroll
Implement traditional pagination for data tables where users need to skip to specific pages or reference exact locations. Reserve infinite scroll for feed-like interfaces or continuous discovery streams where exact positioning is irrelevant.
Expand / Collapse Components
For elements that toggle states, use the down chevron when it is collapsed, and the up chevron when it is expanded.
Text Truncation
When handling long text in constrained spaces (like table cells or small cards), use a single-line text ellipsis paired with a tooltip to reveal the full content on hover. Wrap text to the next line only in dedicated detail views or expansive prose areas.
Forms & Actions
Autofocus
Reduce friction by automatically focusing the primary input or action button when a view or modal renders. Use the HTML autofocus attribute wherever the user's immediate next step is highly predictable.
Destructive Actions
Always require explicit confirmation dialogs for deletions or irreversible actions. Destructive buttons must use the error color variant to signal danger and must never be the default focused element when a view renders.
Form Submissions
- Disable submit buttons when validation fails and errors are already visible.
- On successful submission, disable the button to prevent duplicate requests and display a loading spinner and update the button label to acknowledge the action, such as “Saving...”
System Feedback & Error States
Alerts & Notifications
Use top-right Toast Notifications exclusively for temporary success states or transient feedback. Use inline Alerts (using the outline variant) for persistent, page-level issues or warnings that require user resolution.
Empty States
When a table or list has no data, never leave it completely blank. Always include a relevant icon or illustration, a concise helpful message explaining the empty state, and a clear call-to-action (CTA) to help the user create their first item.
No documents
Create your first document to get started.
404 & 500 Pages
Dead ends and server errors should stay friendly and helpful. Clearly explain what went wrong without exposing technical details, and always include a prominent action that takes users back to the Dashboard or Homepage. For example, 404 pages can intelligently extract segments or slugs from the broken URL and enable searching for it.
Data Loading & Processing
Always provide immediate visual feedback for all user interactions. Utilize skeletons, loading icons, and progress indicators to clearly communicate system status and assure users that their action has been registered while work completes in the background.
Optimistic Loading & SWR
Implement Stale-While-Revalidate (SWR) patterns for frequently accessed entities. Save repetitive data (e.g., task assignees, tags) locally. Render the UI immediately from the local cache while silently fetching updates in the background using Nuxt's useAsyncData or useFetch.
Skeletons & Initial Load States
Always provide structural visual feedback during initial data fetches using Skeletons or loading indicators. Never display an empty "No Data" state while a request is still pending, as this confuses users and creates visual jarring when data finally populates.
Action Feedback
Consistently communicate processing status for user interactions. Apply the loading prop to buttons triggering asynchronous operations. During this state, disable alternative actions (like cancel buttons) to prevent interrupted or orphaned requests.
Asynchronous Modals
Always render modals and slide-overs immediately upon user interaction. If the component requires remote data, display internal loading states (such as skeletons) within the modal instead of delaying its appearance. Delaying the render causes unresponsive UI feedback and confuses users.
Search & Input Debouncing
Enforce a 300ms debounce delay on all text inputs that trigger server-side queries. This standardizes API performance across the application, prevents race conditions, and ensures the UI remains responsive while the user is actively typing.
Formatting
Date & Time Formats
Always display absolute dates using the MMM DD, YYYY format (e.g., Oct 12, 2024) instead of numeric structures like MM/DD/YYYY to prevent regional confusion. Relative timestamps (e.g., "2 hours ago") can be mixed alongside this standard for recent events.
Currency Formatting
Standardize currency displays with the symbol immediately preceding the amount and comma separators for thousands. Include exactly two decimal places for exact financial values (e.g., $1,000.00), and drop the decimals only in high-level, whole-number summaries (e.g., $1,000).
Capitalization
Strictly utilize Sentence case for modern, conversational interfaces. Apply this to all buttons, menus, and form labels (e.g., "Create new project"). Reserve Title Case exclusively for proper nouns, brand entities, and primary page headings.
Pluralization
Always use proper pluralization. For example, use 1 Person and 0 Persons. For words like "Company," do not simply append "s"; use correct morphology like "Companies". Only use the singular form exclusively for the count of 1. Use the plural form for 0, negative values, and indeterminate values.
Accessibility (a11y)
Keyboard Focus States
Keyboard focus rings must never be disabled via CSS without providing a custom visual fallback. When stripping default browser outlines using outline-none, it must always be paired with focus-visible:ring to guarantee clear, accessible navigation for keyboard users.
Image Alt Text
Provide descriptive alt text for all meaningful images to support screen readers. For purely decorative images that do not convey essential information, strictly use an empty alt="" attribute so assistive technologies can safely skip them.
<img src="revenue-chart.png" alt="Q3 Revenue Growth Chart" /> <img src="background-blob.svg" alt="" /> Contrast Ratio
Ensure all UI elements meet WCAG 2.1 AA contrast requirements, maintaining a minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text and UI components in both light and dark modes.
Icons & Tooltips
Use a tooltip for icons without text. Include an `aria-label` to suggest screen readers what the icon does.
Preferred Libraries
Nuxt UI
Our primary component library. Design system is heavily based on this. Used for almost all our web applications and digital interfaces to ensure consistency and speed.
Lucide Icons
Standard UI actions use Lucide. Use Simple Icons strictly for brand logos or when Lucide is insufficient. Use other icon sets of these two don't suffice.
Quasar Framework
Reserved for a few enterprise software where its comprehensive components accelerate development.
Brand Naming & Terminology
Writing the Brand Name
The brand name is a proper noun and should always be written with a single upper-case 'A', accompanied by lower-case letters.
Awecode
Casing Exceptions
Logo Imagery
AWECODE
Domains & Email
awecode.com
Legal Entities
Use these exact names on all legal papers, official letters, and financial vouchers:
- Awecode Solutions Pvt Ltd
- Awecode LLC