pacnpal/thrillwiki_django_no_react
1
1
Fork 0
mirror of https://github.com/pacnpal/thrillwiki_django_no_react.git synced 2025-12-20 15:51:08 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
cb944485b82d6d7b5a8a0616fdc8e7700b264607
thrillwiki_django_no_react/memory-bank/design-system/modern-css-implementation.md
pacnpal 6ce2c30065 Add base HTML template with responsive design and dark mode support 
- Created a new base HTML template for the ThrillWiki project.
- Implemented responsive navigation with mobile support.
- Added dark mode functionality using Alpine.js and CSS variables.
- Included Open Graph and Twitter meta tags for better SEO.
- Integrated HTMX for dynamic content loading and search functionality.
- Established a design system with CSS variables for colors, typography, and spacing.
- Included accessibility features such as skip to content links and focus styles.
2025-09-19 14:08:49 -04:00

16 KiB
Raw Blame History

Modern CSS Implementation Guide

Overview

This document provides comprehensive implementation guidelines for modern CSS techniques in the ThrillWiki frontend redesign, including CSS Grid, Flexbox, custom properties, and advanced CSS features for optimal performance and maintainability.

CSS Architecture

Layer-Based Organization

/* CSS Cascade Layers for better control */
@layer reset, tokens, base, components, utilities, overrides;

@layer reset {
  /* Modern CSS Reset */
  *,
  *::before,
  *::after {
    box-sizing: border-box;
  }
  
  * {
    margin: 0;
  }
  
  body {
    line-height: 1.5;
    -webkit-font-smoothing: antialiased;
  }
  
  img,
  picture,
  video,
  canvas,
  svg {
    display: block;
    max-width: 100%;
  }
  
  input,
  button,
  textarea,
  select {
    font: inherit;
  }
  
  p,
  h1,
  h2,
  h3,
  h4,
  h5,
  h6 {
    overflow-wrap: break-word;
  }
  
  #root,
  #__next {
    isolation: isolate;
  }
}

@layer tokens {
  /* Design tokens from design-tokens.md */
  :root {
    /* Import all design tokens here */
  }
}

@layer base {
  /* Base element styles */
  html {
    scroll-behavior: smooth;
  }
  
  @media (prefers-reduced-motion: reduce) {
    html {
      scroll-behavior: auto;
    }
  }
  
  body {
    font-family: var(--font-family-base);
    font-size: var(--text-base);
    line-height: var(--leading-normal);
    color: var(--text-primary);
    background-color: var(--bg-primary);
    transition: background-color var(--transition-base), color var(--transition-base);
  }
}

@layer components {
  /* Component styles */
}

@layer utilities {
  /* Utility classes */
}

@layer overrides {
  /* Framework overrides and specificity fixes */
}

CSS Custom Properties Implementation

Dynamic Theme System

:root {
  /* Light theme (default) */
  --color-primary-50: #eff6ff;
  --color-primary-100: #dbeafe;
  --color-primary-500: #3b82f6;
  --color-primary-900: #1e3a8a;
  
  /* Semantic color mappings */
  --bg-primary: var(--color-neutral-50);
  --bg-secondary: var(--color-neutral-100);
  --text-primary: var(--color-neutral-900);
  --text-secondary: var(--color-neutral-600);
}

[data-theme="dark"] {
  /* Dark theme overrides */
  --bg-primary: var(--color-neutral-900);
  --bg-secondary: var(--color-neutral-800);
  --text-primary: var(--color-neutral-50);
  --text-secondary: var(--color-neutral-300);
}

/* System preference detection */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --bg-primary: var(--color-neutral-900);
    --bg-secondary: var(--color-neutral-800);
    --text-primary: var(--color-neutral-50);
    --text-secondary: var(--color-neutral-300);
  }
}

Contextual Custom Properties

/* Component-scoped custom properties */
.card {
  --card-padding: var(--spacing-component-lg);
  --card-radius: var(--radius-lg);
  --card-shadow: var(--shadow-md);
  
  padding: var(--card-padding);
  border-radius: var(--card-radius);
  box-shadow: var(--card-shadow);
  background: var(--bg-elevated);
}

.card--compact {
  --card-padding: var(--spacing-component-md);
  --card-radius: var(--radius-md);
  --card-shadow: var(--shadow-sm);
}

.card--featured {
  --card-padding: var(--spacing-component-xl);
  --card-shadow: var(--shadow-lg);
}

CSS Grid Implementation

Advanced Grid Patterns

/* Intrinsic Web Design Grid */
.auto-grid {
  --min-column-width: 250px;
  --grid-gap: var(--spacing-layout-md);
  
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(var(--min-column-width), 100%), 1fr));
  gap: var(--grid-gap);
}

/* Named Grid Lines */
.page-grid {
  display: grid;
  grid-template-columns: 
    [full-start] minmax(var(--spacing-layout-md), 1fr)
    [content-start] min(65ch, calc(100% - 2 * var(--spacing-layout-md)))
    [content-end] minmax(var(--spacing-layout-md), 1fr)
    [full-end];
  grid-template-rows: auto 1fr auto;
}

.page-header {
  grid-column: full;
  background: var(--bg-elevated);
}

.page-content {
  grid-column: content;
}

.page-footer {
  grid-column: full;
  background: var(--bg-secondary);
}

/* Subgrid Implementation (when supported) */
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: var(--spacing-layout-md);
}

.card {
  display: grid;
  grid-template-rows: subgrid;
  grid-row: span 3;
}

/* Fallback for browsers without subgrid */
@supports not (grid-template-rows: subgrid) {
  .card {
    display: flex;
    flex-direction: column;
  }
  
  .card-content {
    flex: 1;
  }
}

Grid Areas and Template Areas

/* Complex Layout with Grid Areas */
.dashboard {
  display: grid;
  grid-template-areas:
    "header header header"
    "sidebar main aside"
    "footer footer footer";
  grid-template-columns: 250px 1fr 300px;
  grid-template-rows: auto 1fr auto;
  min-height: 100vh;
  gap: var(--spacing-layout-md);
}

.dashboard-header { grid-area: header; }
.dashboard-sidebar { grid-area: sidebar; }
.dashboard-main { grid-area: main; }
.dashboard-aside { grid-area: aside; }
.dashboard-footer { grid-area: footer; }

/* Responsive Grid Areas */
@media (max-width: 1024px) {
  .dashboard {
    grid-template-areas:
      "header"
      "main"
      "aside"
      "footer";
    grid-template-columns: 1fr;
  }
  
  .dashboard-sidebar {
    display: none;
  }
}

Flexbox Implementation

Advanced Flexbox Patterns

/* Holy Grail Layout with Flexbox */
.holy-grail {
  display: flex;
  flex-direction: column;
  min-height: 100vh;
}

.holy-grail-body {
  display: flex;
  flex: 1;
}

.holy-grail-content {
  flex: 1;
  padding: var(--spacing-layout-md);
}

.holy-grail-nav,
.holy-grail-ads {
  flex: 0 0 200px;
  padding: var(--spacing-layout-sm);
}

.holy-grail-nav {
  order: -1;
}

/* Flexible Card Layout */
.card-flex {
  display: flex;
  flex-direction: column;
  height: 100%;
}

.card-header,
.card-footer {
  flex-shrink: 0;
}

.card-body {
  flex: 1;
  display: flex;
  flex-direction: column;
  justify-content: space-between;
}

/* Centering Patterns */
.center-flex {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 50vh;
}

.center-flex-column {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  text-align: center;
  gap: var(--spacing-component-lg);
}

Flexible Navigation Patterns

/* Responsive Navigation */
.nav-flex {
  display: flex;
  align-items: center;
  justify-content: space-between;
  flex-wrap: wrap;
  gap: var(--spacing-component-md);
}

.nav-brand {
  flex-shrink: 0;
}

.nav-links {
  display: flex;
  align-items: center;
  gap: var(--spacing-component-md);
  flex-wrap: wrap;
}

.nav-actions {
  display: flex;
  align-items: center;
  gap: var(--spacing-component-sm);
  margin-left: auto;
}

/* Breadcrumb Navigation */
.breadcrumb {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
  gap: var(--spacing-component-xs);
}

.breadcrumb-item {
  display: flex;
  align-items: center;
  gap: var(--spacing-component-xs);
}

.breadcrumb-item:not(:last-child)::after {
  content: '/';
  color: var(--text-tertiary);
}

Container Queries

Component-Based Responsive Design

/* Container Query Setup */
.card-container {
  container-type: inline-size;
  container-name: card;
}

.sidebar-container {
  container-type: inline-size;
  container-name: sidebar;
}

/* Container Query Rules */
@container card (min-width: 300px) {
  .card {
    display: flex;
    flex-direction: row;
    align-items: flex-start;
  }
  
  .card-image {
    flex: 0 0 40%;
  }
  
  .card-content {
    flex: 1;
    padding: var(--spacing-component-lg);
  }
}

@container card (min-width: 500px) {
  .card-title {
    font-size: var(--text-xl);
  }
  
  .card-content {
    padding: var(--spacing-component-xl);
  }
}

@container sidebar (max-width: 200px) {
  .sidebar-nav-text {
    display: none;
  }
  
  .sidebar-nav-icon {
    margin: 0 auto;
  }
}

Advanced CSS Features

CSS Logical Properties

/* Logical properties for internationalization */
.content {
  padding-inline: var(--spacing-layout-md);
  padding-block: var(--spacing-layout-sm);
  margin-block-end: var(--spacing-layout-lg);
  border-inline-start: 3px solid var(--color-primary-500);
}

.card {
  inline-size: 100%;
  max-inline-size: 400px;
  block-size: auto;
  min-block-size: 200px;
}

/* Text alignment */
.text-start { text-align: start; }
.text-end { text-align: end; }

CSS Nesting (when supported)

/* CSS Nesting for better organization */
.card {
  background: var(--bg-elevated);
  border-radius: var(--radius-lg);
  padding: var(--spacing-component-lg);
  
  & .card-title {
    font-size: var(--text-lg);
    font-weight: var(--font-weight-semibold);
    margin-block-end: var(--spacing-component-sm);
    
    & a {
      color: inherit;
      text-decoration: none;
      
      &:hover {
        color: var(--color-primary-600);
        text-decoration: underline;
      }
    }
  }
  
  & .card-content {
    color: var(--text-secondary);
    line-height: var(--leading-relaxed);
  }
  
  &:hover {
    box-shadow: var(--shadow-lg);
    transform: translateY(-2px);
  }
}

CSS Scroll Snap

/* Scroll snap for carousels and galleries */
.carousel {
  display: flex;
  overflow-x: auto;
  scroll-snap-type: x mandatory;
  scroll-behavior: smooth;
  gap: var(--spacing-component-md);
  padding: var(--spacing-component-md);
}

.carousel-item {
  flex: 0 0 300px;
  scroll-snap-align: start;
  scroll-snap-stop: always;
}

/* Vertical scroll snap for sections */
.page-sections {
  height: 100vh;
  overflow-y: auto;
  scroll-snap-type: y mandatory;
}

.page-section {
  height: 100vh;
  scroll-snap-align: start;
  display: flex;
  align-items: center;
  justify-content: center;
}

CSS Aspect Ratio

/* Modern aspect ratio control */
.aspect-square {
  aspect-ratio: 1 / 1;
}

.aspect-video {
  aspect-ratio: 16 / 9;
}

.aspect-photo {
  aspect-ratio: 4 / 3;
}

.aspect-golden {
  aspect-ratio: 1.618 / 1;
}

/* Responsive aspect ratios */
.hero-image {
  aspect-ratio: 21 / 9;
  object-fit: cover;
  width: 100%;
}

@media (max-width: 768px) {
  .hero-image {
    aspect-ratio: 16 / 9;
  }
}

@media (max-width: 480px) {
  .hero-image {
    aspect-ratio: 4 / 3;
  }
}

Performance Optimizations

CSS Containment

/* Layout containment for performance */
.card {
  contain: layout style paint;
}

.sidebar {
  contain: layout;
}

.carousel-item {
  contain: layout style paint;
}

/* Size containment for fixed-size components */
.avatar {
  contain: size layout style paint;
  width: 40px;
  height: 40px;
}

CSS Transform Optimizations

/* Use transform for animations instead of layout properties */
.slide-in {
  transform: translateX(-100%);
  transition: transform var(--duration-300) var(--ease-out);
}

.slide-in.is-visible {
  transform: translateX(0);
}

/* Use will-change sparingly */
.will-animate {
  will-change: transform;
}

.animation-complete {
  will-change: auto;
}

/* GPU acceleration for smooth animations */
.smooth-transform {
  transform: translateZ(0);
  backface-visibility: hidden;
  perspective: 1000px;
}

Critical CSS Patterns

/* Above-the-fold critical styles */
.critical {
  /* Essential layout and typography */
  font-family: var(--font-family-base);
  line-height: var(--leading-normal);
  color: var(--text-primary);
  background-color: var(--bg-primary);
}

.critical-layout {
  display: grid;
  grid-template-rows: auto 1fr auto;
  min-height: 100vh;
}

/* Defer non-critical styles */
@media print, (min-width: 0) {
  .non-critical {
    /* Decorative styles, animations, etc. */
  }
}

Accessibility Enhancements

Focus Management

/* Enhanced focus indicators */
.focus-visible {
  outline: 2px solid var(--color-primary-500);
  outline-offset: 2px;
  border-radius: var(--radius-sm);
}

/* High contrast mode support */
@media (prefers-contrast: high) {
  .card {
    border: 1px solid;
  }
  
  .btn {
    border: 2px solid;
  }
}

/* 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;
    scroll-behavior: auto !important;
  }
}

Screen Reader Optimizations

/* Screen reader only content */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

.sr-only-focusable:focus {
  position: static;
  width: auto;
  height: auto;
  padding: inherit;
  margin: inherit;
  overflow: visible;
  clip: auto;
  white-space: normal;
}

/* Skip links */
.skip-link {
  position: absolute;
  top: -40px;
  left: 6px;
  background: var(--bg-elevated);
  color: var(--text-primary);
  padding: 8px;
  text-decoration: none;
  border-radius: var(--radius-md);
  z-index: 1000;
  transition: top var(--duration-200) var(--ease-out);
}

.skip-link:focus {
  top: 6px;
}

CSS Debugging and Development

Debug Utilities

/* Debug mode for development */
[data-debug="true"] * {
  outline: 1px solid red;
}

[data-debug="true"] *:hover {
  outline: 2px solid blue;
}

/* Grid debugging */
.debug-grid {
  background-image: 
    linear-gradient(rgba(255, 0, 0, 0.1) 1px, transparent 1px),
    linear-gradient(90deg, rgba(255, 0, 0, 0.1) 1px, transparent 1px);
  background-size: 20px 20px;
}

/* Flexbox debugging */
.debug-flex > * {
  outline: 1px solid rgba(0, 255, 0, 0.5);
}

CSS Custom Properties for Debugging

:root {
  --debug-color: red;
  --debug-opacity: 0.1;
}

.debug-outline {
  outline: 1px solid var(--debug-color);
  background: rgba(255, 0, 0, var(--debug-opacity));
}

Browser Support and Fallbacks

Progressive Enhancement

/* Flexbox fallback for CSS Grid */
.grid-fallback {
  display: flex;
  flex-wrap: wrap;
  margin: calc(var(--spacing-layout-md) * -0.5);
}

.grid-fallback > * {
  flex: 1 1 300px;
  margin: calc(var(--spacing-layout-md) * 0.5);
}

@supports (display: grid) {
  .grid-fallback {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: var(--spacing-layout-md);
    margin: 0;
  }
  
  .grid-fallback > * {
    margin: 0;
  }
}

/* Custom properties fallback */
.fallback-colors {
  background-color: #ffffff; /* fallback */
  background-color: var(--bg-primary, #ffffff);
  color: #333333; /* fallback */
  color: var(--text-primary, #333333);
}

Feature Detection

/* Container queries fallback */
@supports not (container-type: inline-size) {
  .card-responsive {
    /* Media query fallback */
  }
}

/* Aspect ratio fallback */
@supports not (aspect-ratio: 1 / 1) {
  .aspect-square {
    width: 100%;
    height: 0;
    padding-bottom: 100%;
    position: relative;
  }
  
  .aspect-square > * {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
  }
}

CSS Organization Best Practices

File Structure

styles/
├── 01-settings/
│   ├── _tokens.css
│   └── _config.css
├── 02-tools/
│   ├── _mixins.css
│   └── _functions.css
├── 03-generic/
│   ├── _reset.css
│   └── _normalize.css
├── 04-elements/
│   ├── _typography.css
│   └── _forms.css
├── 05-objects/
│   ├── _layout.css
│   └── _grid.css
├── 06-components/
│   ├── _buttons.css
│   ├── _cards.css
│   └── _navigation.css
├── 07-utilities/
│   ├── _spacing.css
│   └── _display.css
└── main.css

Naming Conventions

/* BEM methodology with modern enhancements */
.block {}
.block__element {}
.block--modifier {}
.block__element--modifier {}

/* Utility classes with responsive prefixes */
.u-margin-top-sm {}
.u-text-center {}
.u-display-none {}

@media (min-width: 768px) {
  .u-md-display-block {}
  .u-md-text-left {}
}

/* Component states */
.is-active {}
.is-loading {}
.is-disabled {}
.has-error {}

This modern CSS implementation guide provides a comprehensive foundation for building performant, maintainable, and accessible stylesheets using the latest CSS features while ensuring broad browser compatibility through progressive enhancement.

Reference in New Issue View Git Blame Copy Permalink