Scss Refactor Agent

SCSS Refactor Agent

Role: Ontology Migration Specialist
Scope: Subdomain SCSS refactoring
Version: 2.1 - High-Density Refactor

Purpose

Migrate legacy CSS/SCSS to Genesis Ontological mixins, ensuring zero-CSS compliance in subdomain files and maintaining three-tier architecture.

When to Use This Skill

Activate when:

• Refactoring existing stylesheets to ontology
• Auditing subdomain SCSS for semantic purity
• Converting raw CSS to ontological patterns
• Ensuring zero-CSS compliance
• Migrating desktop-first to mobile-first

Core Rules

Subdomain SCSS - ZERO raw CSS:

• ❌ NO margin, padding, color, font-size, background
• ❌ NO unit values: px, rem, %
• ❌ NO color values: #hex, rgb(), oklch()
• ✅ ONLY ontological mixins

Theme SCSS - Clean structure:

• ❌ NEVER use @extend (Jekyll errors)
• ✅ Max 3 nesting levels
• ✅ BEM-style naming

→ Complete refactoring guide: .github/instructions/scss.instructions.md

Migration Workflow

1. Analyze Legacy Code

# Find raw CSS properties
grep -E "(margin|padding|color|font-size):" file.scss

# Check for direct values
grep -E "[0-9]+(px|rem|%)" file.scss

2. Map to Ontology

Common Mappings:

→ Complete mappings: /docs/specifications/scss-ontology-system.md

3. Refactor Pattern

Before:

.card {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(20px);
  padding: 2rem;
  border-radius: 12px;
}

After:

.card {
  @include genesis-entity('primary');  // Handles all visual properties
}

4. Validate

npm run test:scss    # Compilation check
npm run lint:scss    # Style check
npm test             # All checks

Quick Reference

Six Categories (89 total — 33 foundational + 56 evolved):

• genesis-environment($logic) - Layout (21 variants)
• genesis-entity($nature) - Visual (17 variants)
• genesis-cognition($intent) - Typography (9 variants)
• genesis-synapse($vector) - Interaction (19 variants)
• genesis-state($condition) - States (14 variants)
• genesis-atmosphere($vibe) - Atmosphere (9 variants)

→ All 89 variants: /docs/specifications/scss-ontology-system.md

Visual Design Element Ownership:

Accessibility Color Rules

When refactoring color values to ontological tokens:

• OKLCH L ≤ 0.55 for text on white/light backgrounds (WCAG AA 4.5:1)
• Never set body color to $text-inverse — causes invisible text on light sections
• Links must have text-decoration: underline (not just color difference)
• Synapse 'navigate' handles this automatically with underline + accessible color

Hierarchy-Level Rules:

→ Full specification: /docs/specifications/ontology-html-mapping.md

Import Rules

DO import in:

• ✅ Subdomain entry files (e.g., assets/css/custom.scss)
• ✅ Standalone files with --- frontmatter

DON'T import in:

• ❌ _sass/includes/ partials (ontology already imported by assets/css/style.scss)
• ❌ _sass/layouts/ partials (creates 22MB bloat)

→ Import guide: .github/instructions/scss.instructions.md

Validation

# Quick validation
./.github/skills/scss-refactor-agent/scripts/validate-scss.sh file.scss

# Full testing
npm test

Resources

Complete Ontology System:

• /docs/specifications/ontology-html-mapping.md - Formal hierarchy rules and visual element ownership
• /docs/specifications/scss-ontology-system.md - All 89 variants, complete API
• _sass/ontology/INTEGRATION-GUIDE.md - Integration guide
• _sass/ontology/_sample.scss - Working examples

Migration:

• _sass/ontology/refactor-agent.md - Automated migration
• .github/instructions/scss.instructions.md - Core standards

Related Skills: responsive-design-agent, futuristic-effects-agent

Version History:

• v2.1 (2026-02-10): High-density refactor - 212→149 lines, enhanced spec references
• v2.0: Initial SCSS refactoring system

Converted and distributed by TomeVault — claim your Tome and manage your conversions.