CSS Styling Standards

Core Principles

• Mobile-first design: Start with mobile styles, enhance for larger screens
• Accessibility compliance: Meet WCAG 2.1 AA standards
• Multilingual support: Proper display of accented characters and different writing systems
• Consistent naming: Use BEM methodology for class naming (unless using Mantine)
• Performance optimization: Minimize CSS size and loading time
• Mantine Integration: Use Mantine UI v8 component system for React frontend

Mantine UI v8 Integration

1. Theme Configuration

// frontend/src/theme.ts
import { createTheme, MantineColorsTuple } from '@mantine/core';

// Custom color palette for Chuukese dictionary
const primaryBlue: MantineColorsTuple = [
  '#e5f4ff',
  '#cde4ff',
  '#9bc5ff',
  '#64a4ff',
  '#3988fe',
  '#1d77fe',
  '#096fff',
  '#005ee4',
  '#0053cd',
  '#0047b5',
];

export const theme = createTheme({
  primaryColor: 'blue',
  colors: {
    blue: primaryBlue,
  },
  fontFamily: "'Noto Sans', 'Arial Unicode MS', sans-serif",
  
  // Chuukese-optimized typography
  headings: {
    fontFamily: "'Noto Sans', 'Arial Unicode MS', sans-serif",
    fontWeight: '600',
  },
  
  // Default to dark color scheme
  defaultColorScheme: 'dark',
  
  // Component overrides for Chuukese text
  components: {
    Text: {
      defaultProps: {
        style: { 
          fontFeatureSettings: "'kern' 1, 'liga' 1" 
        }
      }
    },
    TextInput: {
      defaultProps: {
        styles: {
          input: {
            fontFamily: "'Noto Sans', 'Arial Unicode MS', sans-serif",
          }
        }
      }
    },
    Textarea: {
      defaultProps: {
        styles: {
          input: {
            fontFamily: "'Noto Sans', 'Arial Unicode MS', sans-serif",
            lineHeight: 1.6,
          }
        }
      }
    }
  }
});

2. Mantine Provider Setup

// frontend/src/main.tsx
import '@mantine/core/styles.css';
import '@mantine/notifications/styles.css';

import { MantineProvider } from '@mantine/core';
import { Notifications } from '@mantine/notifications';
import { ModalsProvider } from '@mantine/modals';
import { theme } from './theme';

function App() {
  return (
    <MantineProvider theme={theme} defaultColorScheme="dark">
      <Notifications position="top-right" />
      <ModalsProvider>
        {/* App content */}
      </ModalsProvider>
    </MantineProvider>
  );
}

3. Chuukese Text with Mantine

import { Text, Title, Badge, Card } from '@mantine/core';

// Chuukese word display component
function ChuukeseWord({ word, definition }: { word: string; definition: string }) {
  return (
    <Card shadow="sm" padding="lg" radius="md" withBorder>
      <Title order={3} style={{ fontFeatureSettings: "'kern' 1" }}>
        {word}
      </Title>
      <Text c="dimmed" size="sm" mt="xs">
        {definition}
      </Text>
    </Card>
  );
}

// Translation input with Mantine
function TranslationInput({ direction }: { direction: 'chk_to_en' | 'en_to_chk' }) {
  return (
    <Textarea
      label={direction === 'chk_to_en' ? 'Chuukese Text' : 'English Text'}
      placeholder={direction === 'chk_to_en' 
        ? 'Enter Chuukese text to translate...' 
        : 'Enter English text to translate...'}
      minRows={4}
      autosize
      styles={{
        input: {
          fontFamily: "'Noto Sans', 'Arial Unicode MS', sans-serif",
          fontSize: '1.1rem',
        }
      }}
    />
  );
}

4. Common Mantine Patterns

// Loading state
import { Loader, Center, Stack, Text } from '@mantine/core';

<Center h={200}>
  <Stack align="center">
    <Loader size="lg" />
    <Text c="dimmed">Translating...</Text>
  </Stack>
</Center>

// Notifications
import { notifications } from '@mantine/notifications';

notifications.show({
  title: 'Translation Complete',
  message: 'Your text has been translated successfully',
  color: 'green',
});

// Modals
import { modals } from '@mantine/modals';

modals.openConfirmModal({
  title: 'Delete Entry',
  children: <Text>Are you sure you want to delete this entry?</Text>,
  labels: { confirm: 'Delete', cancel: 'Cancel' },
  confirmProps: { color: 'red' },
  onConfirm: () => handleDelete(),
});

CSS Architecture (Non-Mantine Styles)

1. File Organization

/* Main stylesheet structure */
@import 'normalize.css';           /* CSS reset */
@import 'variables.css';           /* Custom properties */
@import 'typography.css';          /* Font and text styles */
@import 'layout.css';              /* Grid and flexbox layouts */
@import 'components.css';          /* Reusable components */
@import 'utilities.css';           /* Utility classes */
@import 'responsive.css';          /* Media queries */

2. CSS Custom Properties (Variables)

:root {
  /* Colors - should align with Mantine theme */
  --primary-color: #228be6;
  --secondary-color: #64748b;
  --accent-color: #f59e0b;
  --text-color: #c1c2c5;
  --text-light: #909296;
  --background-color: #1a1b1e;
  --surface-color: #25262b;
  
  /* Typography */
  --font-family-primary: 'Noto Sans', 'Arial Unicode MS', sans-serif;
  --font-family-chuukese: 'Noto Sans', 'Doulos SIL', 'Arial Unicode MS', sans-serif;
  --font-size-base: 1rem;
  --font-size-large: 1.125rem;
  --line-height-base: 1.6;
  --line-height-tight: 1.4;
  
  /* Spacing - matches Mantine spacing scale */
  --spacing-xs: 0.625rem;   /* 10px - Mantine xs */
  --spacing-sm: 0.75rem;    /* 12px - Mantine sm */
  --spacing-md: 1rem;       /* 16px - Mantine md */
  --spacing-lg: 1.25rem;    /* 20px - Mantine lg */
  --spacing-xl: 2rem;       /* 32px - Mantine xl */
  
  /* Mantine-aligned breakpoints */
  --breakpoint-xs: 576px;
  --breakpoint-sm: 768px;
  --breakpoint-md: 992px;
  --breakpoint-lg: 1200px;
  --breakpoint-xl: 1400px;
}

/* Dark mode (Mantine default) */
[data-mantine-color-scheme="dark"] {
  --text-color: #c1c2c5;
  --background-color: #1a1b1e;
  --surface-color: #25262b;
}

/* Light mode */
[data-mantine-color-scheme="light"] {
  --text-color: #1f2937;
  --background-color: #ffffff;
  --surface-color: #f9fafb;
}

Component Standards

1. Chuukese Text Display

/* 
 * Chuukese Text Component
 * Purpose: Proper display of Chuukese text with accent support
 * Usage: Apply to any element containing Chuukese content
 */
.chuukese-text {
  font-family: var(--font-family-chuukese);
  font-size: var(--font-size-large);
  line-height: var(--line-height-base);
  direction: ltr;
  unicode-bidi: embed;
  font-feature-settings: 'kern' 1, 'liga' 1;
}

/* Emphasis for Chuukese headings */
.chuukese-text--heading {
  font-weight: 600;
  letter-spacing: 0.02em;
  margin-bottom: var(--spacing-md);
}

/* Inline Chuukese within English text */
.chuukese-text--inline {
  font-style: italic;
  font-weight: 500;
  color: var(--primary-color);
}

2. Translation Interface Components

/* 
 * Translation Input Component
 * Purpose: Input fields for translation interface
 * Dependencies: Requires .form-group wrapper
 */
.translation-input {
  width: 100%;
  min-height: 120px;
  padding: var(--spacing-md);
  border: 2px solid var(--surface-color);
  border-radius: 0.5rem;
  font-family: var(--font-family-chuukese);
  font-size: var(--font-size-base);
  line-height: var(--line-height-base);
  resize: vertical;
  transition: border-color 0.2s ease-in-out;
}

.translation-input:focus {
  outline: none;
  border-color: var(--primary-color);
  box-shadow: 0 0 0 3px hsla(217, 91%, 60%, 0.1);
}

.translation-input--chuukese {
  direction: ltr;
  text-align: left;
}

.translation-input--error {
  border-color: #ef4444;
}

3. Dictionary Entry Component

/* 
 * Dictionary Entry Card
 * Purpose: Display individual dictionary entries
 * Usage: Container for dictionary entry information
 */
.dictionary-entry {
  background: var(--background-color);
  border: 1px solid var(--surface-color);
  border-radius: 0.5rem;
  padding: var(--spacing-lg);
  margin-bottom: var(--spacing-md);
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
  transition: box-shadow 0.2s ease-in-out;
}

.dictionary-entry:hover {
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

.dictionary-entry__word {
  font-size: 1.25rem;
  font-weight: 600;
  color: var(--primary-color);
  margin-bottom: var(--spacing-sm);
}

.dictionary-entry__definition {
  color: var(--text-color);
  margin-bottom: var(--spacing-sm);
}

.dictionary-entry__pronunciation {
  font-family: 'Courier New', monospace;
  font-size: 0.9rem;
  color: var(--text-light);
  background: var(--surface-color);
  padding: var(--spacing-xs) var(--spacing-sm);
  border-radius: 0.25rem;
  display: inline-block;
}

.dictionary-entry__cultural-note {
  font-style: italic;
  color: var(--text-light);
  border-left: 3px solid var(--accent-color);
  padding-left: var(--spacing-sm);
  margin-top: var(--spacing-sm);
}

Layout Standards

1. Grid System

/* 
 * Custom Grid System
 * Purpose: Flexible grid layout for various screen sizes
 */
.grid {
  display: grid;
  gap: var(--spacing-md);
}

.grid--2-col {
  grid-template-columns: 1fr 1fr;
}

.grid--3-col {
  grid-template-columns: repeat(3, 1fr);
}

.grid--auto-fit {
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
}

/* Responsive grid adjustments */
@media (max-width: 768px) {
  .grid--2-col,
  .grid--3-col {
    grid-template-columns: 1fr;
  }
}

2. Container and Spacing

/* 
 * Container Component
 * Purpose: Main content wrapper with responsive max-width
 */
.container {
  width: 100%;
  max-width: 1200px;
  margin: 0 auto;
  padding: 0 var(--spacing-md);
}

@media (min-width: 768px) {
  .container {
    padding: 0 var(--spacing-lg);
  }
}

/* Spacing utilities */
.mb-sm { margin-bottom: var(--spacing-sm); }
.mb-md { margin-bottom: var(--spacing-md); }
.mb-lg { margin-bottom: var(--spacing-lg); }
.mt-sm { margin-top: var(--spacing-sm); }
.mt-md { margin-top: var(--spacing-md); }
.mt-lg { margin-top: var(--spacing-lg); }

Responsive Design

1. Mobile-First Media Queries

/* Base styles for mobile */
.navigation {
  display: flex;
  flex-direction: column;
  padding: var(--spacing-sm);
}

/* Tablet and up */
@media (min-width: 768px) {
  .navigation {
    flex-direction: row;
    justify-content: space-between;
    align-items: center;
    padding: var(--spacing-md);
  }
}

/* Desktop and up */
@media (min-width: 1024px) {
  .navigation {
    padding: var(--spacing-lg);
  }
}

2. Responsive Typography

/* 
 * Fluid Typography
 * Purpose: Responsive font scaling for better readability
 */
.heading-1 {
  font-size: clamp(1.75rem, 4vw, 2.5rem);
  font-weight: 700;
  line-height: var(--line-height-tight);
  margin-bottom: var(--spacing-lg);
}

.heading-2 {
  font-size: clamp(1.5rem, 3vw, 2rem);
  font-weight: 600;
  line-height: var(--line-height-tight);
  margin-bottom: var(--spacing-md);
}

/* Responsive text scaling for Chuukese content */
.chuukese-text {
  font-size: clamp(1rem, 2.5vw, 1.125rem);
}

@media (max-width: 480px) {
  .chuukese-text {
    font-size: 1.125rem; /* Larger on small screens for readability */
  }
}

Accessibility Standards

1. Focus Management

/* 
 * Focus Styles
 * Purpose: Clear visual indication for keyboard navigation
 */
.btn:focus,
.form-input:focus,
.translation-input:focus {
  outline: 2px solid var(--primary-color);
  outline-offset: 2px;
}

/* High contrast focus for better visibility */
@media (prefers-contrast: high) {
  .btn:focus,
  .form-input:focus {
    outline: 3px solid #000;
    outline-offset: 2px;
  }
}

2. Color and Contrast

/* 
 * Color Accessibility
 * Purpose: Ensure sufficient contrast ratios
 */
:root {
  --text-contrast-ratio: 4.5; /* WCAG AA standard */
}

/* High contrast mode support */
@media (prefers-contrast: high) {
  :root {
    --primary-color: #000;
    --text-color: #000;
    --background-color: #fff;
    --surface-color: #f0f0f0;
  }
}

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

Utility Classes

1. Common Utilities

/* Display utilities */
.d-none { display: none; }
.d-block { display: block; }
.d-inline { display: inline; }
.d-inline-block { display: inline-block; }
.d-flex { display: flex; }
.d-grid { display: grid; }

/* Text utilities */
.text-center { text-align: center; }
.text-left { text-align: left; }
.text-right { text-align: right; }
.text-primary { color: var(--primary-color); }
.text-secondary { color: var(--secondary-color); }
.text-muted { color: var(--text-light); }

/* Responsive utilities */
@media (min-width: 768px) {
  .d-md-block { display: block; }
  .d-md-none { display: none; }
  .text-md-left { text-align: left; }
  .text-md-center { text-align: center; }
}

Best Practices

1. Performance Optimization

• Use CSS custom properties for consistent theming
• Minimize the use of expensive properties (box-shadow, gradients)
• Optimize for critical rendering path
• Use efficient selectors (avoid deep nesting)

2. Maintainability

• Follow BEM naming convention
• Group related styles together
• Comment complex or non-obvious styles
• Use meaningful variable names

3. Cross-Browser Compatibility

• Test in major browsers (Chrome, Firefox, Safari, Edge)
• Use autoprefixer for vendor prefixes
• Provide fallbacks for modern CSS features
• Test with different font settings

4. Multilingual Considerations

• Support for RTL languages if needed
• Font stack that supports Unicode characters
• Proper spacing for accented characters
• Consider text expansion/contraction in different languages

Validation Criteria

CSS should:

• ✅ Pass W3C CSS validation
• ✅ Meet WCAG 2.1 AA accessibility standards
• ✅ Display correctly across major browsers
• ✅ Support proper Chuukese text rendering
• ✅ Follow consistent naming conventions
• ✅ Include responsive breakpoints
• ✅ Optimize for performance and loading speed