thedaviddias/Front-End-Checklist / skills/embedded-or-inline-css
embedded-or-inline-css
VerifiedUse when reviewing stylesheets, component styles, and responsive behavior related to Avoid embedded and inline CSS. Check the rendered layout across breakpoints and interaction states before proposing a fix.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 1.7 KB |
| references/rule.md | markdown | 16.0 KB |
references/rule.md
View on GitHub# Avoid embedded and inline CSS
> Embedded and inline CSS are avoided except for critical CSS and performance optimization.
**Priority:** high · **Difficulty:** beginner · **Time:** 15 min
---
Avoid embedded CSS in `<style>` tags and inline CSS except for valid cases like critical CSS, dynamic styling, or performance optimization.
## Code Examples
### Problems with Inline CSS
```html
<!-- ❌ Bad: Inline styles -->
<div style="background-color: red; padding: 20px; margin: 10px; font-size: 16px;">
Content with inline styles
</div>
<p style="color: blue; text-align: center; font-weight: bold;">
Another element with inline styles
</p>
<!-- ❌ Bad: Embedded styles -->
<style>
.header { background: blue; padding: 10px; }
.content { margin: 20px; font-size: 14px; }
.footer { background: gray; padding: 15px; }
</style>
```
### Problems This Creates
```html
<!-- Issues with inline/embedded CSS: -->
<!-- 1. No caching - styles downloaded with every page -->
<!-- 2. Maintenance nightmare - styles scattered throughout HTML -->
<!-- 3. Specificity issues - inline styles have highest specificity -->
<!-- 4. No reusability - same styles repeated multiple times -->
<!-- 5. Hard to debug - styles mixed with markup -->
<!-- 6. Performance impact - larger HTML files -->
```
## Why It Matters
Inline CSS cannot be cached separately, increases HTML payload, breaks separation of concerns, and is harder to maintain in large codebases.
## Correct External CSS Approach
### Proper CSS Structure
```html
<!-- ✅ Good: External CSS -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Page Title</title>
<!-- External CSS files -->
<link rel="stylesheet" href="css/normalize.css">
<link rel="stylesheet" href="css/base.css">
<link rel="stylesheet" href="css/components.css">
<link rel="stylesheet" href="css/layout.css">
</head>
<body>
<div class="header">
<h1 class="header__title">Page Title</h1>
</div>
<main class="content">
<p class="content__text">Content with external CSS classes</p>
</main>
<footer class="footer">
<p class="footer__text">Footer content</p>
</footer>
</body>
</html>
```
### External CSS Files
```css
/* css/base.css */
html {
font-size: 16px;
line-height: 1.5;
}
body {
margin: 0;
font-family: 'Helvetica Neue', Arial, sans-serif;
color: #333;
}
/* css/components.css */
.header {
background: #007bff;
padding: 1rem;
color: white;
}
.header__title {
margin: 0;
font-size: 1.5rem;
}
.content {
margin: 2rem;
max-width: 800px;
}
.content__text {
margin-bottom: 1rem;
line-height: 1.6;
}
.footer {
background: #6c757d;
padding: 1rem;
color: white;
text-align: center;
}
.footer__text {
margin: 0;
font-size: 0.9rem;
}
```
## Valid Use Cases for Inline/Embedded CSS
### 1. Critical Above-the-Fold CSS
```html
<!-- ✅ Valid: Critical CSS for performance -->
<head>
<style>
/* Critical CSS - above-the-fold styles only */
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
margin: 0;
line-height: 1.5;
}
.hero {
height: 100vh;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
display: flex;
align-items: center;
justify-content: center;
color: white;
}
.hero__title {
font-size: 3rem;
text-align: center;
margin: 0;
}
</style>
<!-- Non-critical CSS loaded asynchronously -->
<link rel="preload" href="css/main.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
<noscript><link rel="stylesheet" href="css/main.css"></noscript>
</head>
```
### 2. Dynamic Styling Based on Data
```jsx
// ✅ Valid: React dynamic styles
function ProgressBar({ percentage, color }) {
const dynamicStyles = {
width: `${percentage}%`,
backgroundColor: color,
transition: 'width 0.3s ease'
}
return (
<div className="progress-bar">
<div
className="progress-bar__fill"
style={dynamicStyles}
aria-valuenow={percentage}
role="progressbar"
/>
</div>
)
}
// External CSS for structure
.progress-bar {
width: 100%;
height: 20px;
background-color: #e0e0e0;
border-radius: 10px;
overflow: hidden;
}
.progress-bar__fill {
height: 100%;
border-radius: 10px;
}
```
### 3. CSS-in-JS for Component Styling
```jsx
// ✅ Valid: CSS-in-JS with proper abstraction
const Button = styled.button`
background: ${props => props.primary ? '#007bff' : '#6c757d'};
color: white;
padding: 0.75rem 1.5rem;
border: none;
border-radius: 4px;
font-size: 1rem;
cursor: pointer;
transition: background-color 0.2s ease;
&:hover {
background: ${props => props.primary ? '#0056b3' : '#545b62'};
}
&:disabled {
opacity: 0.6;
cursor: not-allowed;
}
`
// Usage
function App() {
return (
<div>
Primary Button
Secondary Button
</div>
)
}
```
### 4. User Customization
```html
<!-- ✅ Valid: User-customizable styles -->
<div
class="user-widget"
style="--user-theme-color: {{ user.themeColor }}; --user-font-size: {{ user.fontSize }}px;"
>
<h3 class="widget__title">User Dashboard</h3>
<p class="widget__content">Customized content</p>
</div>
```
```css
/* External CSS using custom properties */
.user-widget {
background: var(--user-theme-color, #007bff);
font-size: var(--user-font-size, 16px);
padding: 1rem;
border-radius: 8px;
color: white;
}
.widget__title {
margin: 0 0 0.5rem 0;
font-size: calc(var(--user-font-size, 16px) * 1.25);
}
.widget__content {
margin: 0;
line-height: 1.5;
}
```
## Framework-Specific Best Practices
### React with CSS Modules
```jsx
// ✅ React with CSS Modules
function Button({ variant = 'primary', size = 'medium', children, ...props }) {
const classNames = [
styles.button,
styles[`button--${variant}`],
styles[`button--${size}`]
].join(' ')
return (
<button className={classNames} {...props}>
{children}
</button>
)
}
// Button.module.css
.button {
padding: 0.75rem 1.5rem;
border: none;
border-radius: 4px;
font-size: 1rem;
cursor: pointer;
transition: all 0.2s ease;
font-family: inherit;
}
.button--primary {
background: #007bff;
color: white;
}
.button--primary:hover {
background: #0056b3;
}
.button--secondary {
background: #6c757d;
color: white;
}
.button--small {
padding: 0.5rem 1rem;
font-size: 0.875rem;
}
.button--large {
padding: 1rem 2rem;
font-size: 1.125rem;
}
```
### Vue with Scoped CSS
```vue
<!-- ✅ Vue with scoped CSS -->
<template>
<div class="card" :class="cardClasses">
<header class="card__header" v-if="title">
<h3 class="card__title">{{ title }}</h3>
</header>
<div class="card__content">
<slot />
</div>
<footer class="card__footer" v-if="hasFooter">
<slot name="footer" />
</footer>
</div>
</template>
<script>
props: {
title: String,
variant: {
type: String,
default: 'default',
validator: value => ['default', 'primary', 'success', 'warning', 'danger'].includes(value)
},
elevated: Boolean
},
computed: {
cardClasses() {
return {
[`card--${this.variant}`]: this.variant !== 'default',
'card--elevated': this.elevated
}
},
hasFooter() {
return this.$slots.footer
}
}
}
</script>
<style scoped>
.card {
border: 1px solid #e0e0e0;
border-radius: 8px;
overflow: hidden;
background: white;
transition: box-shadow 0.2s ease;
}
.card--elevated {
box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}
.card--primary {
border-color: #007bff;
}
.card--primary .card__header {
background: #007bff;
color: white;
}
.card__header {
padding: 1rem;
background: #f8f9fa;
border-bottom: 1px solid #e0e0e0;
}
.card__title {
margin: 0;
font-size: 1.125rem;
}
.card__content {
padding: 1rem;
}
.card__footer {
padding: 0.75rem 1rem;
background: #f8f9fa;
border-top: 1px solid #e0e0e0;
}
</style>
```
### Angular with Component Styles
```typescript
// ✅ Angular with component styles
@Component({
selector: 'app-alert',
template: `
<div
class="alert"
[class]="'alert--' + type"
[class.alert--dismissible]="dismissible"
role="alert"
>
<div class="alert__icon" *ngIf="showIcon">
<ng-content select="[slot=icon]"></ng-content>
</div>
<div class="alert__content">
<h4 class="alert__title" *ngIf="title">{{ title }}</h4>
<ng-content></ng-content>
</div>
<button
class="alert__close"
*ngIf="dismissible"
(click)="onDismiss()"
aria-label="Close"
>
×
</button>
</div>
`,
styles: [`
.alert {
padding: 1rem;
border-radius: 4px;
border: 1px solid transparent;
display: flex;
align-items: flex-start;
gap: 0.75rem;
}
.alert--success {
background-color: #d4edda;
border-color: #c3e6cb;
color: #155724;
}
.alert--warning {
background-color: #fff3cd;
border-color: #ffeaa7;
color: #856404;
}
.alert--danger {
background-color: #f8d7da;
border-color: #f5c6cb;
color: #721c24;
}
.alert__content {
flex: 1;
}
.alert__title {
margin: 0 0 0.5rem 0;
font-size: 1.125rem;
}
.alert__close {
background: none;
border: none;
font-size: 1.5rem;
cursor: pointer;
opacity: 0.7;
}
.alert__close:hover {
opacity: 1;
}
`]
})
@Input() type: 'success' | 'warning' | 'danger' = 'success'
@Input() title?: string
@Input() dismissible = false
@Input() showIcon = true
onDismiss() {
// Emit dismiss event
}
}
```
## Linting and Automated Detection
### ESLint Rules for React
```javascript
// .eslintrc.js
module.exports = {
extends: [
'plugin:react/recommended'
],
rules: {
// Warn about inline styles
'react/forbid-component-props': ['warn', {
forbid: [
{
propName: 'style',
message: 'Avoid inline styles. Use CSS classes or CSS-in-JS instead.'
}
]
}],
// Warn about DOM attributes with style
'react/forbid-dom-props': ['warn', {
forbid: [
{
propName: 'style',
message: 'Avoid inline styles. Use CSS classes instead.'
}
]
}]
}
}
```
### Stylelint Configuration
```javascript
// .stylelintrc.js
module.exports = {
extends: ['stylelint-config-standard'],
rules: {
// Disallow empty sources
'no-empty-source': true,
// Require specific patterns for class names
'selector-class-pattern': '^[a-z][a-z0-9]*(-[a-z0-9]+)*(__[a-z0-9]+(-[a-z0-9]+)*)?(--[a-z0-9]+(-[a-z0-9]+)*)?$',
// Limit nesting depth
'max-nesting-depth': 3,
// Disallow unknown properties
'property-no-unknown': true,
// Require specific units for font sizes
'unit-allowed-list': ['px', 'rem', 'em', '%', 'vw', 'vh', 'deg', 's', 'ms']
}
}
```
### PostCSS Plugin for Inline Style Detection
```javascript
// postcss-no-inline-styles.js
const postcss = require('postcss')
module.exports = postcss.plugin('postcss-no-inline-styles', () => {
return (root, result) => {
// This plugin would analyze HTML and warn about inline styles
// Implementation would scan for style attributes in HTML templates
root.walkRules(rule => {
if (rule.selector.includes('[style]')) {
result.warn('Avoid targeting elements with inline styles', {
node: rule
})
}
})
}
})
```
## Performance Optimization Strategies
### Critical CSS Extraction
```javascript
// critical-css-webpack-plugin.js
const critical = require('critical')
const HtmlWebpackPlugin = require('html-webpack-plugin')
class CriticalCSSPlugin {
apply(compiler) {
compiler.hooks.afterEmit.tapAsync('CriticalCSSPlugin', async (compilation, callback) => {
try {
const htmlFiles = Object.keys(compilation.assets)
.filter(name => name.endsWith('.html'))
for (const htmlFile of htmlFiles) {
await critical.generate({
src: `dist/${htmlFile}`,
dest: `dist/${htmlFile}`,
inline: true,
minify: true,
width: 1300,
height: 900,
penthouse: {
blockJSRequests: false
}
})
}
callback()
} catch (error) {
callback(error)
}
})
}
}
// Usage in webpack.config.js
module.exports = {
plugins: [
new HtmlWebpackPlugin({
template: 'src/index.html'
}),
new CriticalCSSPlugin()
]
}
```
### CSS-in-JS Performance Best Practices
```jsx
// ✅ Optimized CSS-in-JS patterns
// 1. Memoize dynamic styles
const Button = memo(styled.button`
padding: 0.75rem 1.5rem;
border: none;
border-radius: 4px;
cursor: pointer;
transition: background-color 0.2s ease;
${props => props.variant === 'primary' && css`
background: #007bff;
color: white;
&:hover {
background: #0056b3;
}
`}
${props => props.variant === 'secondary' && css`
background: #6c757d;
color: white;
&:hover {
background: #545b62;
}
`}
`)
// 2. Extract static styles
const staticButtonStyles = css`
padding: 0.75rem 1.5rem;
border: none;
border-radius: 4px;
cursor: pointer;
transition: background-color 0.2s ease;
`
// 3. Use CSS custom properties for dynamic values
const ThemeProvider = ({ theme, children }) => {
const themeStyles = useMemo(() => ({
'--primary-color': theme.primary,
'--secondary-color': theme.secondary,
'--font-size-base': theme.fontSize + 'px'
}), [theme])
return (
<div style={themeStyles} className="theme-provider">
{children}
</div>
)
}
```
## Best Practices Summary
1. **External CSS First**: Use external stylesheets as the primary styling method
2. **Critical CSS Exception**: Inline only critical above-the-fold CSS
3. **Dynamic Styles**: Use inline styles only for truly dynamic values
4. **Component Architecture**: Use CSS Modules, styled-components, or scoped CSS
5. **Performance**: Minimize inline styles to reduce HTML size
6. **Maintainability**: Keep styles organized and reusable
7. **Caching**: External CSS benefits from browser caching
8. **Separation of Concerns**: Keep styling separate from markup
9. **Linting**: Use tools to detect and prevent inline style usage
10. **Documentation**: Document exceptions and rationale for inline CSS usage
## Migration Strategy
### Converting Inline to External CSS
```javascript
// inline-to-external-converter.js
const fs = require('fs')
const cheerio = require('cheerio')
class InlineToExternalConverter {
constructor() {
this.extractedStyles = new Map()
this.classCounter = 0
}
convertFile(filePath) {
const content = fs.readFileSync(filePath, 'utf8')
const $ = cheerio.load(content)
$('[style]').each((index, element) => {
const $element = $(element)
const inlineStyles = $element.attr('style')
// Generate unique class name
const className = `extracted-${this.classCounter++}`
// Store extracted styles
this.extractedStyles.set(className, inlineStyles)
// Replace inline style with class
$element.removeClass().addClass(className)
$element.removeAttr('style')
})
// Write updated HTML
fs.writeFileSync(filePath, $.html())
return this.generateCSS()
}
generateCSS() {
let css = '/* Extracted inline styles */\n\n'
for (const [className, styles] of this.extractedStyles) {
css += `.${className} {\n`
css += ` ${styles.replace(/;/g, ';\n ')}\n`
css += '}\n\n'
}
return css
}
}
// Usage
const converter = new InlineToExternalConverter()
const extractedCSS = converter.convertFile('index.html')
fs.writeFileSync('extracted-styles.css', extractedCSS)
```
## Verification
### Automated Checks
- Confirm the computed styles match the intended fix in DevTools.
- If the rule affects motion, contrast, or layout stability, verify those user-facing outcomes directly.
### Manual Checks
- Inspect the rendered UI at the breakpoints and interaction states affected by the rule.
- Test at least one mobile and one desktop viewport before shipping.Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |