Web Design and UX Standards¶

// styles/grid.scss
// 12-column grid system with responsive breakpoints
$grid-columns: 12;
$grid-gutter-width: 24px;
$grid-outer-margin: 24px;

// Breakpoint definitions
$breakpoints: (
  xs: 0,      // Mobile portrait
  sm: 576px,  // Mobile landscape
  md: 768px,  // Tablet portrait
  lg: 992px,  // Tablet landscape / Desktop
  xl: 1200px, // Desktop
  xxl: 1400px // Large desktop
);

// Container max-widths
$container-max-widths: (
  sm: 540px,
  md: 720px,
  lg: 960px,
  xl: 1140px,
  xxl: 1320px
);

// Grid mixin
@mixin make-grid($columns: $grid-columns, $gutter: $grid-gutter-width) {
  display: grid;
  grid-template-columns: repeat($columns, 1fr);
  gap: $gutter;

  @each $breakpoint, $value in $breakpoints {
    @media (min-width: $value) {
      &.grid-#{$breakpoint} {
        grid-template-columns: repeat(var(--grid-cols-#{$breakpoint}, $columns), 1fr);
      }
    }
  }
}

// Layout regions
.layout {
  &__header {
    grid-column: 1 / -1;
    min-height: 64px;
  }

  &__sidebar {
    grid-column: span 3;

    @media (max-width: map-get($breakpoints, md)) {
      grid-column: 1 / -1;
    }
  }

  &__main {
    grid-column: span 9;

    @media (max-width: map-get($breakpoints, md)) {
      grid-column: 1 / -1;
    }
  }
}

// styles/spacing.scss
// Base unit: 8px for consistent spatial rhythm
$spacing-unit: 8px;

// Spacing scale
$spacing: (
  0: 0,
  1: $spacing-unit * 0.5,   // 4px
  2: $spacing-unit,         // 8px
  3: $spacing-unit * 1.5,   // 12px
  4: $spacing-unit * 2,     // 16px
  5: $spacing-unit * 3,     // 24px
  6: $spacing-unit * 4,     // 32px
  7: $spacing-unit * 5,     // 40px
  8: $spacing-unit * 6,     // 48px
  9: $spacing-unit * 8,     // 64px
  10: $spacing-unit * 10,   // 80px
  11: $spacing-unit * 12,   // 96px
  12: $spacing-unit * 16    // 128px
);

// Spacing utilities
@each $name, $value in $spacing {
  // Margin utilities
  .m-#{$name} { margin: $value; }
  .mt-#{$name} { margin-top: $value; }
  .mr-#{$name} { margin-right: $value; }
  .mb-#{$name} { margin-bottom: $value; }
  .ml-#{$name} { margin-left: $value; }
  .mx-#{$name} { margin-left: $value; margin-right: $value; }
  .my-#{$name} { margin-top: $value; margin-bottom: $value; }

  // Padding utilities
  .p-#{$name} { padding: $value; }
  .pt-#{$name} { padding-top: $value; }
  .pr-#{$name} { padding-right: $value; }
  .pb-#{$name} { padding-bottom: $value; }
  .pl-#{$name} { padding-left: $value; }
  .px-#{$name} { padding-left: $value; padding-right: $value; }
  .py-#{$name} { padding-top: $value; padding-bottom: $value; }

  // Gap utilities
  .gap-#{$name} { gap: $value; }
}

// styles/elevation.scss
// Material Design inspired elevation system
$shadows: (
  0: none,
  1: (0 1px 3px rgba(0, 0, 0, 0.12), 0 1px 2px rgba(0, 0, 0, 0.24)),
  2: (0 3px 6px rgba(0, 0, 0, 0.15), 0 2px 4px rgba(0, 0, 0, 0.12)),
  3: (0 10px 20px rgba(0, 0, 0, 0.15), 0 3px 6px rgba(0, 0, 0, 0.10)),
  4: (0 14px 28px rgba(0, 0, 0, 0.25), 0 10px 10px rgba(0, 0, 0, 0.22)),
  5: (0 19px 38px rgba(0, 0, 0, 0.30), 0 15px 12px rgba(0, 0, 0, 0.22))
);

// Elevation mixins
@mixin elevation($level) {
  @if map-has-key($shadows, $level) {
    box-shadow: map-get($shadows, $level);
  } @else {
    @warn "Invalid elevation level: #{$level}";
  }
}

// Component elevation standards
.card {
  @include elevation(1);
  transition: box-shadow 0.3s cubic-bezier(0.4, 0, 0.2, 1);

  &:hover {
    @include elevation(3);
  }
}

.modal {
  @include elevation(5);
}

.dropdown {
  @include elevation(2);
}

.tooltip {
  @include elevation(2);
}

// styles/z-index.scss
// Centralized z-index management
$z-layers: (
  base: 0,
  dropdown: 1000,
  sticky: 1100,
  fixed: 1200,
  modal-backdrop: 1300,
  modal: 1400,
  popover: 1500,
  tooltip: 1600,
  notification: 1700,
  debug: 9999
);

// Z-index function
@function z($layer) {
  @if map-has-key($z-layers, $layer) {
    @return map-get($z-layers, $layer);
  } @else {
    @warn "Invalid z-index layer: #{$layer}";
    @return 0;
  }
}

// Usage examples
.header--sticky {
  position: sticky;
  z-index: z(sticky);
}

.modal {
  z-index: z(modal);

  &__backdrop {
    z-index: z(modal-backdrop);
  }
}

// styles/typography.scss
// Modular type scale (1.250 - Major Third)
$type-scale-ratio: 1.250;
$type-base-size: 16px;

// Font families
$font-families: (
  sans: (-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif),
  serif: (Georgia, Cambria, "Times New Roman", Times, serif),
  mono: (SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace)
);

// Type scale
$type-scale: (
  xs: $type-base-size / pow($type-scale-ratio, 2),    // 10.24px
  sm: $type-base-size / $type-scale-ratio,            // 12.8px
  base: $type-base-size,                              // 16px
  md: $type-base-size * $type-scale-ratio,            // 20px
  lg: $type-base-size * pow($type-scale-ratio, 2),    // 25px
  xl: $type-base-size * pow($type-scale-ratio, 3),    // 31.25px
  2xl: $type-base-size * pow($type-scale-ratio, 4),   // 39.06px
  3xl: $type-base-size * pow($type-scale-ratio, 5),   // 48.83px
  4xl: $type-base-size * pow($type-scale-ratio, 6)    // 61.04px
);

// Line heights
$line-heights: (
  tight: 1.2,
  snug: 1.375,
  normal: 1.5,
  relaxed: 1.625,
  loose: 2
);

// Font weights
$font-weights: (
  thin: 100,
  light: 300,
  normal: 400,
  medium: 500,
  semibold: 600,
  bold: 700,
  black: 900
);

// Typography mixins
@mixin text-style($size: base, $weight: normal, $line-height: normal) {
  font-size: map-get($type-scale, $size);
  font-weight: map-get($font-weights, $weight);
  line-height: map-get($line-heights, $line-height);
}

// Heading styles
h1, .h1 {
  @include text-style(3xl, bold, tight);
  margin-bottom: map-get($spacing, 4);
}

h2, .h2 {
  @include text-style(2xl, semibold, tight);
  margin-bottom: map-get($spacing, 3);
}

h3, .h3 {
  @include text-style(xl, semibold, snug);
  margin-bottom: map-get($spacing, 3);
}

h4, .h4 {
  @include text-style(lg, medium, snug);
  margin-bottom: map-get($spacing, 2);
}

h5, .h5 {
  @include text-style(md, medium, normal);
  margin-bottom: map-get($spacing, 2);
}

h6, .h6 {
  @include text-style(base, medium, normal);
  margin-bottom: map-get($spacing, 2);
}

// Body text
p {
  @include text-style(base, normal, relaxed);
  margin-bottom: map-get($spacing, 4);
}

// Text utilities
.text-xs { font-size: map-get($type-scale, xs); }
.text-sm { font-size: map-get($type-scale, sm); }
.text-base { font-size: map-get($type-scale, base); }
.text-lg { font-size: map-get($type-scale, lg); }
.text-xl { font-size: map-get($type-scale, xl); }

// styles/content.scss
// Optimal reading experience standards

// Maximum line length for readability
$max-line-length: 65ch;
$comfortable-line-length: 45-75ch;

// Content container
.content {
  max-width: $max-line-length;
  margin-left: auto;
  margin-right: auto;

  // Responsive font sizing
  font-size: clamp(
    map-get($type-scale, base),
    2.5vw,
    map-get($type-scale, md)
  );

  // Paragraph spacing
  p + p {
    margin-top: map-get($spacing, 4);
  }

  // List styling
  ul, ol {
    margin-bottom: map-get($spacing, 4);
    padding-left: map-get($spacing, 5);

    li {
      margin-bottom: map-get($spacing, 2);
    }
  }

  // Blockquote styling
  blockquote {
    margin: map-get($spacing, 6) 0;
    padding-left: map-get($spacing, 4);
    border-left: 4px solid var(--color-primary);
    font-style: italic;
  }

  // Code blocks
  pre {
    margin: map-get($spacing, 4) 0;
    padding: map-get($spacing, 4);
    background-color: var(--color-code-bg);
    border-radius: var(--radius-md);
    overflow-x: auto;
  }

  // Inline code
  code {
    padding: 2px 4px;
    background-color: var(--color-code-bg);
    border-radius: var(--radius-sm);
    font-family: map-get($font-families, mono);
    font-size: 0.875em;
  }
}

// Responsive typography
@media (max-width: map-get($breakpoints, sm)) {
  .content {
    font-size: map-get($type-scale, base);
  }

  h1, .h1 { @include text-style(2xl, bold, tight); }
  h2, .h2 { @include text-style(xl, semibold, tight); }
  h3, .h3 { @include text-style(lg, semibold, snug); }
}

// components/card.scss
.card {
  background: var(--color-surface);
  border-radius: var(--radius-lg);
  @include elevation(1);
  overflow: hidden;
  transition: all 0.3s ease;

  &__media {
    position: relative;
    padding-bottom: 56.25%; // 16:9 aspect ratio
    overflow: hidden;

    img {
      position: absolute;
      top: 0;
      left: 0;
      width: 100%;
      height: 100%;
      object-fit: cover;
    }
  }

  &__content {
    padding: map-get($spacing, 5);
  }

  &__title {
    @include text-style(lg, semibold, snug);
    margin-bottom: map-get($spacing, 2);
  }

  &__description {
    @include text-style(base, normal, normal);
    color: var(--color-text-secondary);
    margin-bottom: map-get($spacing, 4);
  }

  &__actions {
    display: flex;
    gap: map-get($spacing, 3);
    margin-top: auto;
  }

  // Interactive states
  &--interactive {
    cursor: pointer;

    &:hover {
      @include elevation(3);
      transform: translateY(-2px);
    }

    &:active {
      @include elevation(1);
      transform: translateY(0);
    }
  }
}

// components/table.scss
.table {
  width: 100%;
  border-collapse: collapse;
  background: var(--color-surface);

  &__header {
    background: var(--color-surface-variant);
    border-bottom: 2px solid var(--color-border);
  }

  &__row {
    border-bottom: 1px solid var(--color-border-light);

    &:hover {
      background: var(--color-surface-hover);
    }

    &--selected {
      background: var(--color-surface-selected);
    }
  }

  &__cell {
    padding: map-get($spacing, 3) map-get($spacing, 4);
    text-align: left;

    &--numeric {
      text-align: right;
      font-feature-settings: "tnum" 1; // Tabular numbers
    }

    &--actions {
      text-align: right;
      white-space: nowrap;
    }
  }

  &__header-cell {
    @extend .table__cell;
    @include text-style(sm, semibold, normal);
    color: var(--color-text-secondary);
    text-transform: uppercase;
    letter-spacing: 0.05em;
  }

  // Responsive table
  @media (max-width: map-get($breakpoints, md)) {
    &--responsive {
      display: block;

      .table__header {
        display: none;
      }

      .table__row {
        display: block;
        margin-bottom: map-get($spacing, 4);
        border: 1px solid var(--color-border);
        border-radius: var(--radius-md);
      }

      .table__cell {
        display: flex;
        justify-content: space-between;

        &::before {
          content: attr(data-label);
          font-weight: map-get($font-weights, semibold);
        }
      }
    }
  }
}

// styles/colors.scss
// Semantic color system with light/dark theme support

// Brand colors
$brand-colors: (
  primary: #1976d2,
  primary-light: #42a5f5,
  primary-dark: #1565c0,
  secondary: #dc004e,
  secondary-light: #e33371,
  secondary-dark: #9a0036
);

// Neutral palette
$neutral-colors: (
  0: #ffffff,
  50: #fafafa,
  100: #f5f5f5,
  200: #eeeeee,
  300: #e0e0e0,
  400: #bdbdbd,
  500: #9e9e9e,
  600: #757575,
  700: #616161,
  800: #424242,
  900: #212121,
  1000: #000000
);

// Semantic colors
$semantic-colors: (
  success: #4caf50,
  success-light: #80e27e,
  success-dark: #087f23,
  warning: #ff9800,
  warning-light: #ffcc80,
  warning-dark: #c66900,
  error: #f44336,
  error-light: #ff7961,
  error-dark: #ba000d,
  info: #2196f3,
  info-light: #6ec6ff,
  info-dark: #0069c0
);

// Theme definitions
:root {
  // Light theme (default)
  --color-primary: #{map-get($brand-colors, primary)};
  --color-primary-light: #{map-get($brand-colors, primary-light)};
  --color-primary-dark: #{map-get($brand-colors, primary-dark)};
  --color-secondary: #{map-get($brand-colors, secondary)};

  --color-background: #{map-get($neutral-colors, 50)};
  --color-surface: #{map-get($neutral-colors, 0)};
  --color-surface-variant: #{map-get($neutral-colors, 100)};

  --color-text-primary: #{map-get($neutral-colors, 900)};
  --color-text-secondary: #{map-get($neutral-colors, 600)};
  --color-text-disabled: #{map-get($neutral-colors, 400)};

  --color-border: #{map-get($neutral-colors, 300)};
  --color-border-light: #{map-get($neutral-colors, 200)};

  --color-success: #{map-get($semantic-colors, success)};
  --color-warning: #{map-get($semantic-colors, warning)};
  --color-error: #{map-get($semantic-colors, error)};
  --color-info: #{map-get($semantic-colors, info)};
}

// Dark theme
[data-theme="dark"] {
  --color-background: #{map-get($neutral-colors, 900)};
  --color-surface: #{map-get($neutral-colors, 800)};
  --color-surface-variant: #{map-get($neutral-colors, 700)};

  --color-text-primary: #{map-get($neutral-colors, 50)};
  --color-text-secondary: #{map-get($neutral-colors, 300)};
  --color-text-disabled: #{map-get($neutral-colors, 600)};

  --color-border: #{map-get($neutral-colors, 700)};
  --color-border-light: #{map-get($neutral-colors, 800)};

  --color-success: #{map-get($semantic-colors, success-light)};
  --color-warning: #{map-get($semantic-colors, warning-light)};
  --color-error: #{map-get($semantic-colors, error-light)};
  --color-info: #{map-get($semantic-colors, info-light)};
}