Brightness System Skill
Overview
The omer-akben portfolio implements an 8-mode brightness system that must be tested and supported for all UI changes. This skill covers implementation patterns, testing requirements, and troubleshooting.
8 Brightness Modes
Modes: -3 (darkest) → 0 (baseline) → +3 (brightest) + auto
Implementation
-
data-brightness attribute on <html> element
-
CSS custom properties in globals.css
-
State management in lib/brightness-context.tsx
CSS Custom Properties (MANDATORY)
Color Tokens
✅ ALWAYS USE:
/* Surfaces / bg-surf-0 / Primary background / bg-surf-1 / Secondary background / bg-surf-2 / Tertiary background */
/* Text / text-text-1 / Primary text / text-text-2 / Secondary text / text-text-3 / Tertiary text */
/* Brand / bg-brand-primary / Brand accent color / bg-brand-secondary / Secondary brand color */
/* Borders / border-border-line / Border color */
❌ **NEVER USE:**
- Hardcoded hex colors: `#00FFC6`, `#1a1a1a`
- Inline color values: `bg-[#00FFC6]`
- Direct Tailwind colors without tokens
### Example Implementation
```tsx
// ✅ CORRECT
<div className="bg-surf-1 text-text-1 border-border-line">
<button className="bg-brand-primary hover:bg-brand-secondary">
Click me
</button>
</div>
// ❌ WRONG
<div className="bg-[#1a1a1a] text-white border-gray-800">
<button className="bg-[#00FFC6] hover:bg-emerald-400">
Click me
</button>
</div>
```typescript
## Implementation Patterns
### Setting Brightness Mode
```typescript
import { useBrightness } from "@/lib/brightness-context";
function BrightnessControl() {
const { brightness, setBrightness } = useBrightness();
return (
<select
value={brightness}
onChange={(e) => setBrightness(e.target.value as BrightnessMode)}
>
<option value="-3">Darkest (-3)</option>
<option value="-2">Darker (-2)</option>
<option value="-1">Dark (-1)</option>
<option value="0">Baseline (0)</option>
<option value="1">Light (+1)</option>
<option value="2">Lighter (+2)</option>
<option value="3">Lightest (+3)</option>
<option value="auto">Auto</option>
</select>
);
}
```typescript
### Brightness Context Provider
Location: `src/lib/brightness-context.tsx`
```typescript
export type BrightnessMode = "-3" | "-2" | "-1" | "0" | "1" | "2" | "3" | "auto";
interface BrightnessContextType {
brightness: BrightnessMode;
setBrightness: (mode: BrightnessMode) => void;
}
```typescript
### HTML Attribute
The brightness mode is set on the root HTML element:
```html
<html data-brightness="0">
<!-- content -->
</html>
```typescript
CSS custom properties respond to this attribute:
```css
[data-brightness="0"] {
--color-surf-0: #0a0a0a;
--color-text-1: #ffffff;
}
[data-brightness="3"] {
--color-surf-0: #f5f5f5;
--color-text-1: #0a0a0a;
}
```typescript
## Testing Requirements
### ⚠️ CRITICAL: Test All 8 Modes
**Every UI change MUST be tested in all 8 brightness modes.**
### Manual Testing
1. Open DevTools (F12)
2. Find `<html>` element in Elements tab
3. Modify `data-brightness` attribute manually
4. Test each mode: `-3`, `-2`, `-1`, `0`, `1`, `2`, `3`, `auto`
5. Verify:
- Text is readable
- Contrast is sufficient
- Colors follow design tokens
- No hardcoded colors appear
### Unit Test Pattern
```typescript
import { render } from "@testing-library/react";
describe("Component brightness modes", () => {
const modes = ["-3", "-2", "-1", "0", "1", "2", "3", "auto"];
modes.forEach((mode) => {
it(`should render correctly in brightness mode ${mode}`, () => {
// Set mode on root
document.documentElement.setAttribute("data-brightness", mode);
render(<YourComponent />);
// Assert appearance
const element = screen.getByRole("button");
expect(element).toHaveClass("bg-brand-primary");
expect(element).not.toHaveClass("bg-[#00FFC6]");
});
});
});
```typescript
### E2E Test Pattern
```typescript
import { test, expect } from "@playwright/test";
test.describe("Brightness modes", () => {
const modes = ["-3", "-2", "-1", "0", "1", "2", "3", "auto"];
modes.forEach((mode) => {
test(`should display correctly in mode ${mode}`, async ({ page }) => {
await page.goto("/");
// Set brightness mode
await page.evaluate((m) => {
document.documentElement.setAttribute("data-brightness", m);
}, mode);
// Wait for CSS to apply
await page.waitForTimeout(100);
// Take screenshot for visual comparison
await expect(page).toHaveScreenshot(`brightness-${mode}.png`);
});
});
});
```typescript
## Common Issues & Solutions
### Issue: Hardcoded Colors Appear
**Symptoms:** Colors don't change with brightness mode
### Solution
1. Search codebase for hex colors: `#[0-9a-fA-F]{3,6}`
2. Replace with CSS custom properties
3. Verify with `grep -r "#[0-9a-fA-F]" src/`
### Issue: Insufficient Contrast
**Symptoms:** Text hard to read in certain modes
### Solution
1. Review color token values in `globals.css`
2. Adjust contrast ratios (minimum 4.5:1 for normal text)
3. Test with browser DevTools contrast checker
### Issue: Component Not Responding to Mode Changes
**Symptoms:** Component colors stay the same
### Solution
1. Verify component uses CSS custom properties
2. Check if component has inline styles (remove them)
3. Ensure parent elements don't override tokens
## Design Token Reference
Complete list of available tokens in `src/app/globals.css`:
```css
/* Surface Colors */
--color-surf-0: /* Primary surface */
--color-surf-1: /* Secondary surface */
--color-surf-2: /* Tertiary surface */
/* Text Colors */
--color-text-1: /* Primary text */
--color-text-2: /* Secondary text */
--color-text-3: /* Tertiary text */
/* Brand Colors */
--color-brand-primary: /* Primary brand (emerald) */
--color-brand-secondary: /* Secondary brand */
/* Border Colors */
--color-border-line: /* Default border */
/* Functional Colors */
--color-error: /* Error state */
--color-success: /* Success state */
--color-warning: /* Warning state */
```typescript
## Checklist for New Components
When creating a new component:
- [ ] Use only CSS custom properties for colors
- [ ] No hardcoded hex colors or Tailwind color classes
- [ ] Test component in all 8 brightness modes
- [ ] Verify contrast ratios meet WCAG AA (4.5:1)
- [ ] Check hover states in all modes
- [ ] Verify focus indicators are visible in all modes
- [ ] Test with auto mode (respects system preference)
## Auto Mode Behavior
When `brightness="auto"`:
- Respects user's system preference (light/dark)
- Uses `prefers-color-scheme` media query
- Maps to mode `0` (dark) or mode `2` (light) by default
```css
[data-brightness="auto"] {
@media (prefers-color-scheme: dark) {
/* Use dark mode tokens */
}
@media (prefers-color-scheme: light) {
/* Use light mode tokens */
}
}
```typescript
## Performance Considerations
- CSS custom properties are performant (no runtime calculation)
- Mode changes only update root attribute (no re-renders)
- Tailwind processes tokens at build time
- No JavaScript needed for color computation
## Related Files
- `src/lib/brightness-context.tsx` - Context provider and hooks
- `src/app/globals.css` - Color token definitions
- `src/components/brightness-toggle.tsx` - UI control (if exists)
## Quick Reference
```bash
# Find hardcoded colors in codebase
grep -r "#[0-9a-fA-F]" src/
# Test brightness modes in browser DevTools
document.documentElement.setAttribute("data-brightness", "3")
# Check component uses correct tokens
// Should see: bg-surf-1, text-text-1, border-border-line
// Should NOT see: bg-[#xxx], text-white, border-gray-800
```typescript