Skip to content

styling-system.md

Latest commit

 

History

History
284 lines (216 loc) · 6.6 KB

styling-system.md

File metadata and controls

284 lines (216 loc) · 6.6 KB

Styling System

🎨 CSS Layer Architecture

The application uses a sophisticated CSS layer system for optimal styling organization and cascade control.

Layer Configuration

// styles.scss
@layer tailwind-base, primeng, tailwind-utilities;

@layer tailwind-base {
  @tailwind base;
}

@layer tailwind-utilities {
  @tailwind components;
  @tailwind utilities;
}

PrimeNG Integration with CSS Layers

// app.config.ts - PrimeNG configuration with CSS layers
const customPreset = definePreset(Aura, {
  primitive: lfxPreset.primitive,
  semantic: lfxPreset.semantic,
  components: lfxPreset.component,
});

providePrimeNG({
  theme: {
    preset: customPreset,
    options: {
      prefix: 'p',
      darkModeSelector: '.dark-mode',
      cssLayer: {
        name: 'primeng',
        order: 'tailwind-base, primeng, tailwind-utilities',
      },
    },
  },
});

Layer Benefits

  1. Proper CSS Cascade: Ensures Tailwind utilities can override PrimeNG styles
  2. Predictable Specificity: Layer order determines precedence regardless of selector specificity
  3. Maintainable Styles: Clear separation of concerns between frameworks
  4. Performance: Optimized CSS loading and parsing

🎯 LFX UI Core Integration

The customPreset shown above is built from LFX UI Core design tokens via definePreset(Aura, lfxPreset), configuring primitive tokens, semantic color mappings, and component-specific styles.

Design System Benefits

  • Consistent Branding: LFX design tokens throughout the application
  • Accessible Colors: WCAG compliant color combinations
  • Responsive Design: Mobile-first responsive patterns
  • Dark Mode Support: Built-in dark mode theming capabilities

🌈 Color System

LFX Brand Colors

// Colors imported from @lfx-one/shared package
// Defined in packages/shared/src/constants/colors.constants.ts
import { lfxColors } from '@lfx-one/shared/constants';

Usage in Tailwind

// tailwind.config.js
import PrimeUI from 'tailwindcss-primeui';
import { lfxColors } from '@lfx-one/shared/constants';

export default {
  theme: {
    extend: {
      colors: lfxColors,
    },
  },
  plugins: [PrimeUI],
};

🔤 Font System

Font Configuration

// Custom font theme variables
@theme {
  --font-inter: 'Inter', ui-sans-serif, system-ui, sans-serif;
  --font-display: 'Roboto Slab', ui-serif, Georgia, serif;
  --font-serif: 'Roboto Slab', ui-serif, Georgia, serif;
}

Font Loading

Fonts are loaded via Google Fonts for optimal performance:

  • Inter: Primary sans-serif font for all UI text
  • Roboto Slab: Display font for headings and emphasis

Custom Font Sizes

// packages/shared/src/constants/font-sizes.constants.ts (imported via @lfx-one/shared)
export const lfxFontSizes = {
  '2xs': ['0.625rem', { lineHeight: '0.75rem' }],
  xs: ['0.75rem', { lineHeight: '1rem' }],
  // ... additional sizes
};

🛠 Tailwind Configuration

Core Configuration

// tailwind.config.js
import PrimeUI from 'tailwindcss-primeui';
import { lfxColors } from '@lfx-one/shared/constants';
import { lfxFontSizes } from '@lfx-one/shared/constants';

export default {
  content: ['./src/**/*.{html,ts}'],
  theme: {
    extend: {
      colors: lfxColors,
      fontSize: lfxFontSizes,
      fontFamily: {
        inter: ['Inter', 'sans-serif'],
        display: ['Roboto Slab', 'serif'],
        serif: ['Roboto Slab', 'serif'],
      },
    },
  },
  plugins: [PrimeUI],
};

Note: Colors and font sizes are imported from @lfx-one/shared package, not local config files. The Tailwind config uses ESM syntax (export default).

Note: While Open Sans is the declared sans font, Inter is explicitly applied to body text elements (h1-h6, p, label, button, input) in styles.scss and is the primary visible font. The inter font family utility class is available via Tailwind.

PrimeUI Plugin Integration

The tailwindcss-primeui plugin provides:

  • Component utilities for PrimeNG components
  • Consistent spacing and sizing
  • Integrated design tokens
  • Responsive utilities

🎨 Component Styling Guidelines

Utility-First Approach

<!-- Preferred: Utility classes -->
<div class="flex items-center gap-4 p-6 bg-white rounded-lg shadow-sm">
  <lfx-avatar [image]="user.picture" class="w-12 h-12"></lfx-avatar>
  <div class="flex-1">
    <h3 class="text-lg font-semibold text-gray-900">{{ user.name }}</h3>
    <p class="text-sm text-gray-600">{{ user.email }}</p>
  </div>
</div>

Component-Specific Styles

When utilities aren't sufficient, use component-specific styles:

// component.scss
.custom-component {
  @apply relative overflow-hidden;

  &:hover {
    @apply shadow-lg transform scale-105;
    transition: all 0.2s ease-in-out;
  }

  .special-element {
    background: linear-gradient(45deg, theme('colors.primary.500'), theme('colors.secondary.500'));
  }
}

🎭 Icon System

Font Awesome Pro

Icons are loaded via Font Awesome kits (not npm packages):

<!-- Icon usage -->
<i class="fa-light fa-user"></i>
<i class="fa-solid fa-check"></i>
<i class="fa-regular fa-heart"></i>

Icon Guidelines

  • Use fa-light for most interface icons
  • Use fa-solid for emphasis and CTAs
  • Use fa-regular for secondary actions
  • Maintain consistent icon sizing
  • Provide accessible labels

🌓 Dark Mode Support

Theme Configuration

// PrimeNG dark mode selector
options: {
  darkModeSelector: '.dark-mode',
}

Implementation

<!-- Dark mode toggle -->
<button (click)="toggleDarkMode()" class="p-2 rounded-md dark:bg-gray-800 dark:text-white">
  <i class="fa-light fa-moon dark:fa-sun"></i>
</button>

📱 Responsive Design

Breakpoint Strategy

// Tailwind breakpoints
const breakpoints = {
  sm: '640px',
  md: '768px',
  lg: '1024px',
  xl: '1280px',
  '2xl': '1536px',
};

Responsive Patterns

<!-- Mobile-first responsive design -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <lfx-project-card class="w-full" [title]="project.name" [description]="project.description"> </lfx-project-card>
</div>

🔧 Build Optimizations

CSS Purging

Unused CSS is automatically removed in production builds:

// tailwind.config.js
export default {
  content: ['./src/**/*.{html,ts}'],
  // Only CSS used in these files is included
};

Critical CSS

Critical CSS is inlined for faster initial renders:

  • Above-the-fold styles are prioritized
  • Non-critical styles are loaded asynchronously
  • Font loading is optimized with preload hints