# Scss Refactor Agent

> Migrate legacy CSS and SCSS to Genesis Ontological mixins. Convert raw CSS properties to semantic ontological patterns, ensure zero-CSS compliance in subdomain files, and maintain the three-tier architecture. Use when refactoring existing stylesheets to adopt the ontology system or auditing subdomain SCSS for semantic purity. Use when this capability is needed.

- Skill: `tomevault-io/scss-refactor-agent` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/scss-refactor-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/scss-refactor-agent/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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

```bash
# 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:**

| Legacy CSS | Ontology Mixin |
|-----------|----------------|
| Layout/grid | `genesis-environment('distributed')` |
| Card styling | `genesis-entity('primary')` |
| Typography | `genesis-cognition('discourse')` |
| Buttons | `genesis-synapse('execute')` |
| Loading states | `genesis-state('evolving')` |
| Dark theme | `genesis-atmosphere('void')` |

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

### 3. Refactor Pattern

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

**After:**
```scss
.card {
  @include genesis-entity('primary');  // Handles all visual properties
}
```

### 4. Validate

```bash
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:**

| Semantic Purpose | Owner | Visual Design Element |
|-----------------|-------|---------------------|
| Responsive spatial rhythm — gaps signal section vs group boundaries | `environment` | White space / gap |
| Component breathing room — variant-scaled density | `entity` | Internal padding |
| Page mood and emotional tone — OKLCH: `void`=black, `ethereal`=translucent, `sacred`=gradient | `atmosphere` | Colors / backgrounds |
| Information voice and reading intent — `axiom`=bold headlines, `discourse`=serif body, `protocol`=monospace | `cognition` | Typography |
| Component edge treatment — 1px subtle, 2px neon accent, 999px pill via `--radius-bento` | `entity` | Borders / shape |
| Lifecycle transitions and temporal signaling — `evolving`=sweep gradient, `scroll-triggered`=fade-in-up, `deprecated`=dimmed | `state` | Animations |
| Action-specific interaction feedback — `navigate`=hover underline, `execute`=neon glow, 44px WCAG touch targets | `synapse` | Hover / focus |

### 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:**

| Level | Required | Forbidden |
|-------|----------|-----------|
| 1 — Page Layout | `environment` + `atmosphere` | `entity`, `cognition`, `synapse` |
| 2 — Section | `environment` | `entity`, `cognition` |
| 3 — Component | `entity` | — |
| 4 — Leaf | `cognition` or `synapse` | `environment`, `atmosphere`, `entity` |

→ **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

```bash
# 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](https://tomevault.io/claim/asisaga) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->