dart-sass

## When to use this skill

Use this skill whenever the user wants to:
- Install and configure Dart Sass
- Compile Sass/SCSS files to CSS
- Use Sass syntax features (variables, nesting, mixins, functions, etc.)
- Work with Sass modules and imports
- Integrate Sass into build tools or workflows
- Use Sass CLI commands
- Configure Sass compilation options
- Use Sass in JavaScript or Dart projects
- Optimize Sass compilation performance
- Handle Sass source maps

## How to use this skill

To use Dart Sass:

1. **Install Dart Sass**:
   - Load `examples/getting-started/installation.md` for installation instructions
   - Load `examples/getting-started/basic-usage.md` for basic usage examples
   - Load `examples/getting-started/compiling-modes.md` for different compilation modes

2. **Learn Sass syntax**:
   - Load `examples/syntax/variables.md` for variable usage
   - Load `examples/syntax/nesting.md` for nesting syntax
   - Load `examples/syntax/mixins.md` for mixins
   - Load `examples/syntax/functions.md` for functions
   - Load `examples/syntax/operators.md` for operators
   - Load `examples/syntax/at-rules.md` for at-rules

3. **Use advanced features**:
   - Load `examples/features/modules.md` for module system
   - Load `examples/features/imports.md` for imports
   - Load `examples/features/control-flow.md` for control flow
   - Load `examples/features/built-in-modules.md` for built-in modules
   - Load `examples/features/source-maps.md` for source maps
   - Load `examples/features/custom-functions.md` for custom functions

4. **Reference the API documentation** when needed:
   - `api/js-api.md` - JavaScript API reference
   - `api/dart-api.md` - Dart API reference
   - `api/cli-api.md` - CLI command reference

5. **Use templates** for quick start:
   - `templates/basic-project.md` - Basic Sass project template
   - `templates/modular-project.md` - Modular Sass project template
   - `templates/build-integration.md` - Build tool integration template


### Doc mapping (one-to-one with official documentation)

- `examples/` → https://sass-lang.com/documentation/

## Examples and Templates

This skill includes detailed examples organized to match the official documentation structure. All examples are in the `examples/` directory (see mapping above).

**To use examples:**
- Identify the topic from the user's request
- Load the appropriate example file from the mapping above
- Follow the instructions, syntax, and best practices in that file
- Adapt the code examples to your specific use case

**To use templates:**
- Reference templates in `templates/` directory for common scaffolding
- Adapt templates to your specific needs and coding style

### Inline Quick Start

```bash
# Install
npm install --save-dev sass

# Compile once
npx sass src/styles.scss dist/styles.css

# Watch for changes
npx sass --watch src/styles.scss:dist/styles.css

# Production (compressed)
npx sass src/styles.scss dist/styles.css --style=compressed --no-source-map
```

```scss
// src/styles.scss — using @use module system
@use 'sass:math';
@use './variables' as vars;

.container {
  max-width: vars.$max-width;
  padding: math.div(vars.$spacing, 2);
}

@mixin responsive($breakpoint) {
  @media (min-width: $breakpoint) { @content; }
}

.hero {
  font-size: 1.5rem;
  @include responsive(768px) {
    font-size: 2rem;
  }
}
```

## API Reference

- **JavaScript API**: `api/js-api.md` - JavaScript API for compiling Sass (compile, compileString, etc.)
- **Dart API**: `api/dart-api.md` - Dart API for compiling Sass
- **CLI API**: `api/cli-api.md` - Command-line interface options and usage

## Best Practices

1. **Use @use instead of @import**: The @import rule is deprecated, use @use and @forward instead
2. **Organize with modules**: Use the module system to organize and share code
3. **Optimize compilation**: Use appropriate output style (compressed for production)
4. **Source maps**: Enable source maps for development, disable for production
5. **Watch mode**: Use --watch for development to automatically recompile on changes
6. **Load paths**: Use --load-path to simplify import paths
7. **Performance**: Use Dart Sass for best performance (faster than Ruby Sass)
8. **Version control**: Don't commit compiled CSS files, only commit Sass source files

## Troubleshooting

- **@import deprecation warning**: Replace `@import` with `@use` and `@forward`; update variable references to use namespaces
- **Compilation errors**: Check for missing semicolons, unmatched braces, or invalid nesting
- **Missing module**: Verify `@use` path is correct relative to the file; use `--load-path` for shared directories
- **Slow compilation**: Use `--watch` during development; consider splitting large files into partials

## Resources

- **Official Website**: https://sass-lang.com/dart-sass/
- **Installation Guide**: https://sass-lang.com/install/
- **Documentation**: https://sass-lang.com/documentation/
- **GitHub Repository**: https://github.com/sass/dart-sass
- **npm Package**: https://www.npmjs.com/package/sass
- **pub.dev Package**: https://pub.dev/packages/sass

## Keywords

dart-sass, sass, scss, css preprocessor, sass compiler, sass syntax, sass modules, sass mixins, sass functions, sass variables, sass nesting, @use, @forward, @import, @include, @mixin, @function, sass:math, sass:color, sass:string, source maps, sass cli, sass api, 样式预处理器, Sass 编译器, Sass 语法, Sass 模块, Sass 混合, Sass 函数