LOKE Design System
Guides

Design Principles

Core principles guiding the LOKE Design System — consistency, accessibility, responsiveness, performance, clarity, and feedback.

Design Principles

This document outlines the core design principles that guide the LOKE Design System. These principles help maintain consistency, quality, and usability across all LOKE applications.

Consistency

Consistency is key to providing a cohesive user experience across all LOKE products. This means using the same patterns, components, and styles throughout our applications.

Guidelines

  • Use design system components rather than creating custom variants
  • Maintain consistent spacing using the design system's spacing scale
  • Follow established patterns for similar interactions
  • Use consistent terminology in the interface

Examples

Good:

// Using standard design system components
<Card>
  <CardHeader>
    <CardTitle>Transaction Details</CardTitle>
  </CardHeader>
  <CardContent>
    <p>Transaction information</p>
  </CardContent>
  <CardFooter>
    <Button>Confirm</Button>
  </CardFooter>
</Card>

Avoid:

// Creating custom card-like components
<div className="border rounded-lg p-4 shadow-md">
  <div className="mb-4 border-b pb-2">
    <h3 className="text-lg font-medium">Transaction Details</h3>
  </div>
  <div>
    <p>Transaction information</p>
  </div>
  <div className="border-t pt-4 mt-4">
    <button className="bg-blue-500 text-white px-4 py-2 rounded">Confirm</button>
  </div>
</div>

Modularity

Build complex interfaces from simple, reusable components. This approach makes our code more maintainable and allows for greater flexibility.

Guidelines

  • Compose complex UIs from simple components
  • Keep components focused on a single responsibility
  • Use layout components (Box, Stack, Columns) to structure content
  • Avoid creating monolithic components with many responsibilities

Examples

Good:

<Stack gap={4}>
  <Heading>User Profile</Heading>
  <UserInfoCard user={user} />
  <AccountStats stats={user.stats} />
  <RecentActivity activities={user.activities} />
</Stack>

Avoid:

<UserProfilePage
  username={user.name}
  email={user.email}
  avatar={user.avatar}
  stats={user.stats}
  activities={user.activities}
  // ... many more props
/>

Accessibility

All LOKE interfaces must be accessible to all users, including those with disabilities. This isn't just a nice-to-have; it's an essential design requirement.

Guidelines

  • Ensure sufficient color contrast for text and interactive elements
  • Provide text alternatives for non-text content
  • Ensure keyboard navigability for all interactive elements
  • Use semantic HTML and ARIA attributes correctly
  • Test with screen readers and other assistive technologies

Examples

Good:

<Button aria-label="Settings">
  <Settings className="h-5 w-5" />
</Button>

// Or using VisuallyHidden
<Button>
  <VisuallyHidden>Settings</VisuallyHidden>
  <Settings className="h-5 w-5" />
</Button>

Avoid:

<button>
  <Settings className="h-5 w-5" />
</button>

Responsiveness

LOKE applications should work well on all device sizes and orientations. Our design system includes responsive capabilities built into its components.

Guidelines

  • Use responsive component props for adaptable layouts
  • Test on different screen sizes including mobile and large displays
  • Avoid fixed dimensions that might break on smaller screens
  • Implement appropriate touch targets for mobile interfaces

Examples

Good:

<Columns columns={[1, 2, 3, 4]} gap={[2, 4]}>
  <Card>Content 1</Card>
  <Card>Content 2</Card>
  <Card>Content 3</Card>
  <Card>Content 4</Card>
</Columns>

Avoid:

<div className="grid grid-cols-4 gap-4">
  <Card>Content 1</Card>
  <Card>Content 2</Card>
  <Card>Content 3</Card>
  <Card>Content 4</Card>
</div>

// This will be 4 columns on all screen sizes, which is problematic on mobile

Performance

User interfaces should be fast and efficient, avoiding unnecessary complexity that might impact performance.

Guidelines

  • Import only the components and utilities you need
  • Use memoization for expensive computations
  • Avoid excessive re-renders by using appropriate hooks and patterns
  • Consider code splitting for large applications
  • Test performance on lower-end devices

Examples

Good:

// Import only what you need
import { Button } from '@loke/design-system/button';
import { Card } from '@loke/design-system/card';

Avoid:

// Importing everything
import * as DesignSystem from '@loke/design-system';

// Using deeply nested destructuring that may prevent tree-shaking
const { Button, Card } = DesignSystem;

Clarity

Interfaces should be clear and intuitive, helping users accomplish their goals without confusion.

Guidelines

  • Use clear, descriptive labels for interactive elements
  • Provide helpful feedback for user actions
  • Use appropriate visual hierarchy to guide user attention
  • Balance simplicity and functionality
  • Use consistent patterns for similar interactions

Examples

Good:

<Dialog>
  <DialogTrigger asChild>
    <Button>Open Settings</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Application Settings</DialogTitle>
      <DialogDescription>Adjust your application preferences here.</DialogDescription>
    </DialogHeader>

    {/* Settings content */}

    <DialogFooter>
      <Button type="submit">Save Changes</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

Avoid:

<Button onClick={() => setIsOpen(true)}>Settings</Button>;
{
  isOpen && (
    <div className="fixed inset-0 bg-black/50 flex items-center justify-center">
      <div className="bg-white p-4 rounded">
        <h3>Settings</h3>

        {/* Settings content */}

        <div className="flex justify-end mt-4">
          <button
            onClick={() => {
              saveSettings();
              setIsOpen(false);
            }}
          >
            OK
          </button>
        </div>
      </div>
    </div>
  );
}

Visual Hierarchy

Establish a clear visual hierarchy to guide users through the interface and highlight what's most important.

Guidelines

  • Use typography scale to indicate information hierarchy
  • Apply whitespace strategically to group related elements
  • Use color and contrast to direct attention
  • Consider the reading flow when arranging elements

Examples

Good:

<Card>
  <CardHeader>
    <CardTitle>Quarterly Report</CardTitle>
    <CardDescription>Q3 2023 Financial Results</CardDescription>
  </CardHeader>
  <CardContent>
    <Text size="lg" weight="medium">
      ${revenue.toLocaleString()}
    </Text>
    <Text variant="muted">Total Revenue</Text>

    <Separator className="my-4" />

    <Heading size="sm">Key Metrics</Heading>
    <List>
      <ListItem>New Customers: {newCustomers}</ListItem>
      <ListItem>Retention Rate: {retentionRate}%</ListItem>
    </List>
  </CardContent>
</Card>

Avoid:

<Card>
  <CardContent>
    <p>Q3 2023 Financial Results</p>
    <p>Quarterly Report</p>
    <p>${revenue.toLocaleString()} Total Revenue</p>
    <p>New Customers: {newCustomers}</p>
    <p>Retention Rate: {retentionRate}%</p>
  </CardContent>
</Card>

Feedback

Provide clear feedback to users to confirm their actions and communicate system status.

Guidelines

  • Indicate loading states with appropriate visual cues
  • Confirm successful actions with feedback
  • Show clear error messages when things go wrong
  • Use appropriate animations to communicate state transitions
  • Ensure feedback is accessible to all users

Examples

Good:

<Button onClick={handleSubmit} disabled={isLoading}>
  {isLoading ? (
    <>
      <Loader className="mr-2 h-4 w-4 animate-spin" />
      Submitting...
    </>
  ) : (
    'Submit'
  )}
</Button>;

{
  isSuccess && <Alert variant="success">Form submitted successfully!</Alert>;
}

{
  error && (
    <Alert variant="destructive">
      <AlertTitle>Error</AlertTitle>
      <AlertDescription>{error.message}</AlertDescription>
    </Alert>
  );
}

Avoid:

<button onClick={handleSubmit} disabled={isLoading}>
  Submit
</button>;

{
  isSuccess && <p>Success!</p>;
}

{
  error && <p>Error: Something went wrong.</p>;
}

Conclusion

These design principles are not just guidelines—they represent LOKE's commitment to creating high-quality, user-friendly applications. By following these principles, we ensure that our products are consistent, accessible, and delightful to use.

When implementing interfaces with the LOKE Design System, regularly refer back to these principles to guide your decisions and maintain the high quality standards we strive for.

Tailwind CSS

How Tailwind CSS relates to the LOKE Design System — what's included, what's optional, and when you might want your own setup.

Accessibility Guide

Build accessible interfaces with the LOKE Design System — principles, checklists, examples, and testing guidance.

On this page

Design PrinciplesConsistencyGuidelinesExamplesModularityGuidelinesExamplesAccessibilityGuidelinesExamplesResponsivenessGuidelinesExamplesPerformanceGuidelinesExamplesClarityGuidelinesExamplesVisual HierarchyGuidelinesExamplesFeedbackGuidelinesExamplesConclusion