CarbonMate - VS Code Extension

A VS Code extension that provides Carbon Design System token suggestions for SCSS files. Automatically detects SCSS files and suggests Carbon spacing tokens when writing CSS properties like margin and padding.

Features

• SCSS File Detection: Automatically activates when editing SCSS files
• Carbon Spacing Tokens: Provides suggestions for all Carbon Design System spacing tokens
• Smart Suggestions: Only shows spacing token suggestions when writing margin or padding properties
• Rich Documentation: Each token includes rem and px values with descriptions
• Hardcoded Value Detection: Detects hardcoded spacing values and suggests Carbon token replacements
• Import Awareness: Ensures proper @use '@carbon/layout'; import is present
• Performance Optimized: Only processes active SCSS files for better performance

Carbon Spacing Tokens

The extension provides suggestions for all 13 Carbon spacing tokens:

Installation

From VSIX (Local Installation)

1. Download the latest .vsix file from the Releases page
2. In VS Code, go to Extensions (Ctrl+Shift+X)
3. Click the "..." menu and select "Install from VSIX..."
4. Choose the downloaded .vsix file

From Source

1. Clone this repository
2. Run npm install
3. Run npm run compile
4. Press F5 to run the extension in a new VS Code window

Usage

1. Token Suggestions

1. Open a SCSS file in VS Code
2. Add @use '@carbon/layout'; at the top of the file
3. Start typing a spacing property (margin, padding, etc.)
4. Type $ to trigger the suggestions
5. Select a Carbon spacing token from the dropdown

2. Magic Number Replacement

1. Open a SCSS file with @use '@carbon/layout'; import
2. Notice CarbonMate underlines hardcoded spacing values (e.g., 16px, 1rem, 2em)
3. Use Ctrl+. (Windows/Linux) or Cmd+. (Mac) to quick fix one of the selected value - the extension will suggest the closest Carbon token
4. Alternatively:
   • Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
   • Type CarbonMate
   • Select Fix all hardcoded spacing values
5. The extension will automatically replace all hardcoded values with their closest matching Carbon tokens in the file

Example

@use '@carbon/layout';

.my-component {
  // Manual token usage
  margin: layout.$spacing-05;    // ✅ Correct Carbon syntax
  padding: layout.$spacing-03;   // ✅ Correct Carbon syntax
  
  // Hardcoded values that can be replaced
  margin: 16px;                 // 🔄 Can be replaced with layout.$spacing-05
  padding: 24px;                // 🔄 Can be replaced with layout.$spacing-06
}

Hardcoded Value Detection

The extension can detect and suggest replacements for:

• Pixel values: 16px, 24px, 32px, etc.
• Rem values: 1rem, 1.5rem, 2rem, etc.
• Em values: 1em, 1.5em, 2em, etc.

Replacement Logic

• Exact matches: Direct replacement with corresponding Carbon token
• Close matches: Suggests the closest Carbon token (within 8px difference)
• Far matches: No suggestion (values too far from Carbon tokens)

Examples

Commands

• CarbonMate: Fix All Hardcoded Spacing Values - Replace all hardcoded spacing values in the current file
• CarbonMate: Refresh Code Check - Manually refresh the code analysis

Development

Prerequisites

• Node.js (v16 or higher)
• VS Code

Setup

1. Clone the repository

   git clone https://github.com/your-username/vscode-CarbonMate.git
   cd vscode-CarbonMate
   

2. Install dependencies

   npm install
   

3. Compile the extension

   npm run compile
   

4. Press F5 to run the extension in a new VS Code window

Build Commands

npm run compile    # Compile TypeScript
npm run watch      # Watch for changes and recompile
npm run lint       # Run ESLint

Creating a VSIX Package

npm install -g vsce
vsce package

This will create a .vsix file that can be installed in VS Code.

Configuration

The extension can be configured through VS Code settings:

• carbonmate.enable: Enable/disable the extension (default: true)

Dependencies

• @carbon/layout: Carbon Design System layout tokens
• @types/vscode: VS Code extension API types
• typescript: TypeScript compiler

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Issues

If you find any issues or have suggestions, please open an issue on GitHub.

License

This project is licensed under the ISC License - see the LICENSE file for details.

Acknowledgments

• Carbon Design System for the spacing tokens
• VS Code Extension API for the development framework