SmolWeb CSS Grading Specification

Overview

The SmolWeb validator grades CSS based on performance impact and complexity. Properties are categorized from Grade A (lightweight, mobile-friendly) to Grade F (heavy computational cost).

Grade A allows to use a minimal CSS set. Each grade adds properties and distances the style sheet from the objectives of SmolWeb.

Bear in mind that a SmolWeb site must be viewable without applying the style sheet.

Philosophy

SmolWeb promotes minimal, efficient CSS that works well on constrained devices. The grading reflects: - Computational cost (rendering performance) - Mobile compatibility (CSS Mobile Profile 1.0 as baseline) - Simplicity (avoiding over-engineered solutions)

Grade A: Essential & Lightweight

Concept: CSS Mobile Profile 1.0 baseline. These properties work everywhere and have minimal performance impact.

Box Model

• margin, margin-* (top, right, bottom, left)
• padding, padding-* (top, right, bottom, left)
• border, border-* (width, style, color, sides)
• width, height

Typography (Basic)

• font, font-family, font-size, font-weight, font-style, font-variant
• line-height
• text-align, text-decoration, text-indent, text-transform
• color
• white-space

Layout (Basic)

• display (inline, block, list-item, none only)
• float, clear
• vertical-align

Background (Basic)

• background, background-color, background-image
• background-repeat, background-attachment, background-position

Lists

• list-style, list-style-type, list-style-position, list-style-image

Impact: Use freely. These are the foundation of lightweight web design.

Grade B: Basic Responsive Features

Concept: Essential for modern responsive design without significant overhead.

Responsive Design

• @media queries
• max-width, min-width, max-height, min-height

Layout Enhancements

• display: inline-block
• position: relative

Visibility

• visibility

Text Direction

• direction (internationalization)
• align-self, justify-self (when used with flex/grid)

Impact: Necessary for responsive sites. Use thoughtfully but don’t avoid.

Grade C: Useful Additions

Concept: Modern conveniences that enhance UX without major performance penalties.

Visual Polish

• border-radius (rounded corners)
• opacity
• box-sizing (border-box)
• outline, outline-*
• cursor

Text Handling

• text-overflow (ellipsis)
• word-break, word-wrap
• letter-spacing, word-spacing
• tab-size

Content & Overflow

• overflow, overflow-x, overflow-y
• content (pseudo-elements)

CSS Variables

• var(--custom-property)
• Custom properties in: colors, backgrounds, fonts, margins, padding

Advanced Background

• background-size, background-origin, background-clip

Layout Tools

• aspect-ratio
• resize
• gap, row-gap, column-gap

Image & Media

• object-fit, object-position
• image-rendering

Accessibility & UX

• accent-color (form controls)
• caret-color
• scroll-behavior

Text Decoration

• text-underline-offset
• text-decoration-thickness

Impact: Modern CSS that improves UX. Use when beneficial, but be aware each property adds complexity.

Grade D: Moderate Performance Impact

Concept: Useful features with noticeable computational cost. Use selectively.

Positioning

• position: absolute, position: fixed
• top, bottom, left, right
• z-index (stacking contexts)

Flexbox

• display: flex, display: inline-flex
• justify-content, align-items, align-content
• flex, flex-direction, flex-wrap

Table Layout

• display: table, table-cell, table-row, table-column
• table-layout, border-collapse, border-spacing
• caption-side, empty-cells

Visual Effects

• box-shadow
• text-shadow

Font Loading

• @font-face with src (performance impact from loading)

Logical Properties

• block-size, inline-size
• writing-mode, text-orientation

Page/Column Breaks

• break-before, break-after, break-inside

Scroll Control

• scroll-margin, scroll-padding
• touch-action

Text Emphasis

• text-emphasis, text-emphasis-*

Text Decoration

• text-decoration-skip-ink

Impact: Requires layout calculations and reflows. Budget their use carefully. Consider simpler alternatives first.

Grade E: Significant Computational Cost

Concept: Powerful features with substantial performance overhead. Use sparingly.

CSS Grid

• display: grid, display: inline-grid
• grid-template-columns, grid-template-rows
• grid-column, grid-row

Transforms

• transform (matrix calculations)
• transform-origin

Transitions

• transition, transition-* (property, duration, timing, delay)

Sticky Positioning

• position: sticky (constant position recalculation)

Calculated Values

• calc() in: width, height, margin, padding, font-size

Advanced Clipping & Masking

• clip-path
• mask, mask-image

Optimization Hints

• contain (layout containment)
• overscroll-behavior
• content-visibility

Impact: Heavy computational requirements. Only use when simpler solutions won’t work. Test on low-end devices.

Grade F: Heavy Performance Impact

Concept: Maximum computational cost. Avoid unless absolutely necessary.

Animations

• animation, @keyframes
• animation-* (name, duration, timing, delay, iteration, direction, fill-mode, play-state)

Filters

• filter (blur, brightness, contrast, etc.)
• backdrop-filter

3D Transforms

• transform-style
• perspective, perspective-origin
• backface-visibility

Experimental Display

• display: contents, display: run-in

Container Queries

• container-type, container-name

Experimental Features

• view-timeline (scroll timelines)

Impact: Maximum performance impact. Animations and filters are especially expensive on mobile. Use only for critical visual effects. Consider progressive enhancement.

Grading Algorithm

1. Properties are matched in order - first match wins
2. Value-specific rules take precedence over generic ones
   • Example: display: inline → Grade A
   • Example: display: grid → Grade E
3. Wildcards (*) match any value
4. CSS Variables using var() are graded based on usage context
5. Unknown properties/values default to Grade F (caution principle)

Usage Guidelines

For Grade A-B Sites (SmolWeb Ideal)

• Stick to box model, typography, basic layouts
• Use media queries for responsiveness
• Avoid JavaScript dependencies for layout
• Target works on feature phones and old browsers

For Grade C Sites (Modern but Minimal)

• Add polish with border-radius, opacity
• Use CSS variables for theming
• Basic overflow and text handling
• Still performant on mid-range devices

For Grade D Sites (Feature-Rich)

• Flexbox for complex layouts
• Positioned elements when needed
• Shadows for depth
• Test on older mobile devices

For Grade E-F Sites (Performance Budget Required)

• Profile rendering performance
• Use animations sparingly
• Consider progressive enhancement
• Test on low-end hardware

Examples

Grade A Example (Pure SmolWeb)

body {
  font-family: sans-serif;
  line-height: 1.5;
  margin: 1em;
  color: #333;
  background-color: #fff;
}

h1 { font-size: 2em; }
p { margin-bottom: 1em; }
a { color: blue; text-decoration: underline; }

Grade C Example (Modern Minimal)

:root {
  --primary: #0066cc;
  --spacing: 1rem;
}

.card {
  border-radius: 8px;
  padding: var(--spacing);
  box-sizing: border-box;
  overflow: hidden;
}

.truncate {
  white-space: nowrap;
  text-overflow: ellipsis;
}

Grade D Example (Flexbox Layout)

.header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

.modal {
  position: fixed;
  top: 50%;
  left: 50%;
  z-index: 1000;
}

Grade F Example (Heavy Features)

@keyframes pulse {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.5; }
}

.animated {
  animation: pulse 2s infinite;
  filter: blur(2px);
  backdrop-filter: blur(10px);
}

.grid-3d {
  display: grid;
  transform: perspective(1000px) rotateX(10deg);
}

Philosophy Summary

SmolWeb CSS grading prioritizes:

1. Performance on constrained devices
2. Simplicity and maintainability
3. Progressive enhancement
4. Avoiding computational overhead

The best SmolWeb sites use mostly Grade A-B properties with selective use of Grade C for polish. Grades D-F should be justified by user experience benefits and tested thoroughly on low-end devices.

Future Considerations

As browser engines improve, some Grade D-E properties may be reconsidered. The grading reflects current performance characteristics circa 2024-2025 and emphasizes compatibility with older/mobile devices.

Remember: The goal isn’t to avoid modern CSS entirely, but to make informed decisions about the performance trade-offs of each property.