dss/docs/PRINCIPLES_SUMMARY.md

DSS Principles Summary

Complete guide to all coding principles, architectural decisions, and best practices for DSS development.

Last Updated: 2025-12-06 Status: ✅ Complete (Grade A with accessibility focus)

---

Quick Reference

Core Principles (Pick 3 to Remember)

1. Single Source of Truth - Design tokens are the canonical representation
2. Atomic Composition - 5-level hierarchy (Tokens→Primitives→Components→Layouts→Views)
3. Keyboard First - All UI must be accessible via keyboard

---

Organizational Structure

By Topic

🏗️ Architecture

• Monolithic Core Design: Single source of truth with immutable core
• Layered Architecture: Clear separation between storage, domain, ingestion, analysis, generation, and API
• External Translation Pattern: External systems translate TO DSS, not reverse
• Architectural Patterns: Strategy, Abstract Base Classes, Data Classes, Dependency Injection

Reference: DSS_CODING_PRINCIPLES.md Section 1

💻 Code Quality

• Python Style: PEP 8 with 4-space indent, snake_case, 100-char lines
• Error Handling: Explicit exceptions, meaningful messages, no silent failures
• Async Patterns: All I/O must be async via asyncio
• Docstrings: All modules, classes, and public functions documented
• Type Hints: 100% coverage for public APIs, 80% overall target
• Comments: Explain WHY not WHAT, mark TODOs with urgency

Reference: DSS_CODING_PRINCIPLES.md Section 2

🏛️ 7-Layer Architecture

DSS has seven logical layers:

1. Core - Database, configuration, schemas, event bus
2. Ingestion - Token extraction from CSS, Figma, JSON, Tailwind
3. Validation - Schema checking, linting, error detection
4. State - Token models, stores, data flow
5. Processing - Transformations, analysis, style-dictionary
6. Presentation - Admin UI, Storybook, documentation
7. Integration - APIs, MCP tools, webhooks, CLI

Design Principle: Each layer has clear responsibility and health indicators

Reference: Architecture Overview

⌨️ Keyboard Accessibility

• Tabindex Management: Use tabindex="0" on all interactive elements
• Focus Styling: :focus-visible CSS for keyboard users, 3:1 contrast
• Keyboard Handlers: Enter/Space/Escape/Arrows all work as expected
• ARIA Attributes: Label all elements, indicate state, describe errors
• Web Components: Proper lifecycle management, focus delegation

Key Metric: Application fully operable via keyboard only

Reference: DSS_CODING_PRINCIPLES.md Section 4

🔒 Security

• No Global State: Never expose classes to window global
• HTML Sanitization: Always use DOMPurify before inserting HTML
• No Monkey-Patching: Never override native APIs (fetch, etc.)
• Input Validation: Validate at system boundaries only
• Environment Variables: Secrets via env vars, never hardcoded

Reference: DSS_CODING_PRINCIPLES.md Sections 5-6

🎭 Web Components

• Lifecycle Management: Implement connectedCallback() and disconnectedCallback()
• Event Listener Storage: Store handlers on this for cleanup
• Attribute Observation: Include ALL affecting attributes in observedAttributes()
• Focus Delegation: Delegate focus to internal focusable elements
• ARIA Support: Pass through ARIA attributes to internal elements

Reference: DSS_CODING_PRINCIPLES.md Section 5

🎯 Event Handling & Memory

• Event Delegation: Use document-level listeners, not per-element
• Guard Flags: Prevent re-attachment with flags (hasActionListener)
• Data-Driven Actions: Use data-action attributes instead of onclick
• Listener Cleanup: Remove all listeners in disconnectedCallback()
• No Accumulation: Same listener only attached once

Problem Solved: Memory leaks from event listener accumulation in SPAs

Reference: DSS_CODING_PRINCIPLES.md Section 7

---

Principles by Category

If You're Building a Component...

Checklist:

• All interactive elements have tabindex="0"
• Icon buttons have aria-label
• Toggles have aria-expanded
• Form errors have aria-invalid and aria-describedby
• :focus-visible CSS for keyboard users
• Keyboard shortcuts work (Enter, Space, Escape)
• disconnectedCallback() removes all listeners
• Event listeners stored as this.handler
• No HTML inserted via innerHTML without sanitization
• No functions exposed to window
• Works with keyboard-only navigation
• Works with screen readers

Reference: DSS_CODING_PRINCIPLES.md Accessibility Checklist

If You're Designing an API Endpoint...

Checklist:

• Input validation on all parameters
• Clear error messages (no generic 500 errors)
• Async/await for all I/O
• Proper HTTP status codes
• Rate limiting considered
• CORS configured if needed
• Documented in docstring

If You're Adding a New Token Source...

Checklist:

• Extends TokenSource abstract base class
• Implements extract() async method
• Returns TokenCollection with normalized tokens
• Handles all error cases gracefully
• Zero data loss during parsing
• Tests for edge cases (empty files, malformed input)

---

Before You Commit

Code Review Checklist

• All tests pass
• Docstrings added for new functions/classes
• Type hints for new code (100% for public APIs)
• No new bare except: statements
• Error messages are clear and helpful
• No hardcoded secrets (use env vars)
• No console.log/print statements left
• README/docs updated if needed
• Keyboard navigation works
• Accessible to screen readers
• No global state pollution

Accessibility Review Checklist

• Keyboard users can access all features
• Screen reader users get proper labels
• Focus indicator is visible (3:1 contrast)
• Color is not only way to convey information
• All images have alt text
• Form errors are clearly described
• No auto-playing audio/video

---

Important Files

Documentation

• DSS_CODING_PRINCIPLES.md - Complete principles guide
• ARCHITECTURE_REVIEW.md - Architecture decisions
• CODE_QUALITY.md - Quality metrics and standards
• GLOSSARY.md - Corporate terminology
• Architecture Overview - 7-layer system
• First Principles - 7 foundational truths
• Atomic Hierarchy - 5-level composition

Implementation Examples

• Web Components: /admin-ui/js/components/ds-button.js (keyboard + ARIA)
• Web Components: /admin-ui/js/components/ds-input.js (form validation + accessibility)
• Event Delegation: /admin-ui/js/core/app.js (lines 2202-2484)
• Keyboard Handlers: /admin-ui/js/core/app.js (lines 2486-2533)
• Sanitization: /admin-ui/js/core/sanitizer.js (DOMPurify integration)
• Focus CSS: /admin-ui/css/components.css (lines 661-709)
• Accessibility Utilities: /admin-ui/css/base.css (lines 278-293)

---

Learning Path

For New Contributors

1. Start Here: Read PRINCIPLES_SUMMARY.md (this file) - 5 min
2. Terminology: Read GLOSSARY.md - 5 min
3. First Principles: Read First Principles - 10 min
4. Architecture: Read Architecture Overview - 10 min
5. Atomic Hierarchy: Read Atomic Hierarchy - 10 min
6. Code Quality: Review CODE_QUALITY.md - 10 min
7. Complete Guide: Read DSS_CODING_PRINCIPLES.md - 30 min

Total Time: ~80 minutes for complete understanding

For Quick Reference

• "How do I add a button?" → See Web Components section
• "How should I handle errors?" → See Code Quality section
• "Is my keyboard support right?" → See Keyboard Accessibility checklist
• "Where does this go architecturally?" → See Layered Architecture section
• "How do I keep the system healthy?" → See Observable Health in First Principles

---

Key Statistics

Current State (as of 2025-12-06):

Metric	Value	Target
Code Quality Grade	A	A+
Type Hints Coverage	60%	100%
Test Coverage	Basic	80%
Accessibility Compliance	WCAG 2.1 AA	WCAG 2.1 AAA
Documentation	Excellent	Excellent
Keyboard Accessibility	Complete	Fully Tested
ARIA Support	Comprehensive	Comprehensive

---

Frequently Asked Questions

"Can I use window.myVariable for debugging?"

Only in development mode, and always check the environment first:

if (process.env.NODE_ENV === 'development') {
  window.__DSS_DEBUG = { ... };
}

"Should I write comments for my code?"

Comments should explain WHY, not WHAT. Code should be clear enough to explain itself. Only comment:

• Complex algorithms or business logic
• Non-obvious decisions
• TODO items with urgency level

"What if I don't have tests?"

All new public functions should have tests. Start with:

• Happy path test
• Error case test
• Edge case test (if applicable)

"How do I handle accessibility for complex components?"

1. Use semantic HTML elements when possible
2. Add ARIA attributes for dynamic state
3. Test with keyboard navigation (Tab/Shift-Tab)
4. Test with screen reader (NVDA, JAWS, VoiceOver)
5. Check color contrast (3:1 minimum, 4.5:1 for text)

"Do I need to support IE11?"

No. Browser support:

• ✅ Chrome/Edge (last 2 versions)
• ✅ Firefox (last 2 versions)
• ✅ Safari (last 2 versions)
• ❌ IE11 (no longer supported)

---

Governance

Pull Request Requirements

All PRs must demonstrate:

1. ✅ Tests passing
2. ✅ Code quality maintained (no new violations)
3. ✅ Accessibility checklist passed
4. ✅ Documentation updated
5. ✅ At least one approval from maintainer

Decision Log

Major architectural decisions and their rationale are documented in ARCHITECTURE_REVIEW.md.

Contributing

When adding new principles:

1. Update DSS_CODING_PRINCIPLES.md with complete detail
2. Add summary to this file
3. Add implementation example
4. Create or update relevant checklist
5. Link to all related docs

---

External References

• WCAG 2.1 Guidelines - Accessibility standards
• ARIA Authoring Practices - Accessible component patterns
• Web Components Best Practices - Component lifecycle
• PEP 8 - Python style guide
• Clean Code Python - Code quality patterns

---

Summary

The Design System Swarm is a A-grade, production-ready system with:

✅ Strong architecture - Monolithic core, clear layering, separation of concerns ✅ Excellent code quality - Type hints, documentation, error handling ✅ Complete accessibility - Keyboard navigation, ARIA, screen reader support ✅ Secure by design - No global state, HTML sanitization, no monkey-patching ✅ Health monitoring - Observable health at every layer ✅ Clear governance - Review checklists, principles documentation, examples

Next Steps:

• Increase test coverage from "basic" to 80%
• Add type hints to remaining 40% of codebase
• Create integration tests for Figma API
• Monitor accessibility compliance (target: AAA)

---

Remember: Code is read far more often than it's written. Write for readability, accessibility, and maintainability.