{"id":13495875,"url":"https://github.com/necolas/idiomatic-css","last_synced_at":"2025-05-14T09:07:42.657Z","repository":{"id":3383409,"uuid":"4431560","full_name":"necolas/idiomatic-css","owner":"necolas","description":"Principles of writing consistent, idiomatic CSS.","archived":false,"fork":false,"pushed_at":"2022-12-21T12:01:30.000Z","size":791,"stargazers_count":6648,"open_issues_count":7,"forks_count":614,"subscribers_count":270,"default_branch":"master","last_synced_at":"2025-04-08T17:16:11.635Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/necolas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-05-24T10:21:44.000Z","updated_at":"2025-04-08T08:31:33.000Z","dependencies_parsed_at":"2023-01-13T12:28:33.995Z","dependency_job_id":null,"html_url":"https://github.com/necolas/idiomatic-css","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/necolas%2Fidiomatic-css","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/necolas%2Fidiomatic-css/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/necolas%2Fidiomatic-css/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/necolas%2Fidiomatic-css/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/necolas","download_url":"https://codeload.github.com/necolas/idiomatic-css/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254110374,"owners_count":22016391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T19:01:39.138Z","updated_at":"2025-05-14T09:07:42.631Z","avatar_url":"https://github.com/necolas.png","language":null,"readme":"# Principles of writing consistent, idiomatic CSS\n\nThe following document outlines a reasonable style guide for CSS development.\nThese guidelines strongly encourage the use of existing, common, sensible\npatterns. They should be adapted as needed to create your own style guide.\n\nThis is a living document and new ideas are always welcome. Please\ncontribute.\n\n\n## Table of contents\n\n1. [General principles](#general-principles)\n2. [Whitespace](#whitespace)\n3. [Comments](#comments)\n4. [Format](#format)\n5. [Practical example](#example)\n\n[Acknowledgements](#acknowledgements)\n\n[License](#license)\n\n\n\u003ca name=\"general-principles\"\u003e\u003c/a\u003e\n## 1. General principles\n\n\u003e \"Part of being a good steward to a successful project is realizing that\n\u003e writing code for yourself is a Bad Idea™. If thousands of people are using\n\u003e your code, then write your code for maximum clarity, not your personal\n\u003e preference of how to get clever within the spec.\" - Idan Gazit\n\n* Don't try to prematurely optimize your code; keep it readable and\n  understandable.\n* All code in any code-base should look like a single person typed it, even\n  when many people are contributing to it.\n* Strictly enforce the agreed-upon style.\n* If in doubt when deciding upon a style use existing, common patterns.\n\n\n\u003ca name=\"whitespace\"\u003e\u003c/a\u003e\n## 2. Whitespace\n\nOnly one style should exist across the entire source of your code-base. Always\nbe consistent in your use of whitespace. Use whitespace to improve\nreadability.\n\n* _Never_ mix spaces and tabs for indentation.\n* Choose between soft indents (spaces) or real tabs. Stick to your choice\n  without fail. (Preference: spaces)\n* If using spaces, choose the number of characters used per indentation level.\n  (Preference: 4 spaces)\n\nTip: configure your editor to \"show invisibles\" or to automatically remove\nend-of-line whitespace.\n\nTip: use an [EditorConfig](http://editorconfig.org/) file (or equivalent) to\nhelp maintain the basic whitespace conventions that have been agreed for your\ncode-base.\n\n\n\u003ca name=\"comments\"\u003e\u003c/a\u003e\n## 3. Comments\n\nWell commented code is extremely important. Take time to describe components,\nhow they work, their limitations, and the way they are constructed. Don't leave\nothers in the team guessing as to the purpose of uncommon or non-obvious\ncode.\n\nComment style should be simple and consistent within a single code base.\n\n* Place comments on a new line above their subject.\n* Keep line-length to a sensible maximum, e.g., 80 columns.\n* Make liberal use of comments to break CSS code into discrete sections.\n* Use \"sentence case\" comments and consistent text indentation.\n\nTip: configure your editor to provide you with shortcuts to output agreed-upon\ncomment patterns.\n\nExample:\n\n```css\n/* ==========================================================================\n   Section comment block\n   ========================================================================== */\n\n/* Sub-section comment block\n   ========================================================================== */\n\n/**\n * Short description using Doxygen-style comment format\n *\n * The first sentence of the long description starts here and continues on this\n * line for a while finally concluding here at the end of this paragraph.\n *\n * The long description is ideal for more detailed explanations and\n * documentation. It can include example HTML, URLs, or any other information\n * that is deemed necessary or useful.\n *\n * @tag This is a tag named 'tag'\n *\n * TODO: This is a todo statement that describes an atomic task to be completed\n *   at a later date. It wraps after 80 characters and following lines are\n *   indented by 2 spaces.\n */\n\n/* Basic comment */\n```\n\n\n\u003ca name=\"format\"\u003e\u003c/a\u003e\n## 4. Format\n\nThe chosen code format must ensure that code is: easy to read; easy to clearly\ncomment; minimizes the chance of accidentally introducing errors; and results\nin useful diffs and blames.\n\n* Use one discrete selector per line in multi-selector rulesets.\n* Include a single space before the opening brace of a ruleset.\n* Include one declaration per line in a declaration block.\n* Use one level of indentation for each declaration.\n* Include a single space after the colon of a declaration.\n* Use lowercase and shorthand hex values, e.g., `#aaa`.\n* Use single or double quotes consistently. Preference is for double quotes,\n  e.g., `content: \"\"`.\n* Quote attribute values in selectors, e.g., `input[type=\"checkbox\"]`.\n* _Where allowed_, avoid specifying units for zero-values, e.g., `margin: 0`.\n* Include a space after each comma in comma-separated property or function\n  values.\n* Include a semi-colon at the end of the last declaration in a declaration\n  block.\n* Place the closing brace of a ruleset in the same column as the first\n  character of the ruleset.\n* Separate each ruleset by a blank line.\n\n```css\n.selector-1,\n.selector-2,\n.selector-3[type=\"text\"] {\n    -webkit-box-sizing: border-box;\n    -moz-box-sizing: border-box;\n    box-sizing: border-box;\n    display: block;\n    font-family: helvetica, arial, sans-serif;\n    color: #333;\n    background: #fff;\n    background: linear-gradient(#fff, rgba(0, 0, 0, 0.8));\n}\n\n.selector-a,\n.selector-b {\n    padding: 10px;\n}\n```\n\n#### Declaration order\n\nIf declarations are to be consistently ordered, it should be in accordance with\na single, simple principle.\n\nSmaller teams may prefer to cluster related properties (e.g. positioning and\nbox-model) together.\n\n```css\n.selector {\n    /* Positioning */\n    position: absolute;\n    z-index: 10;\n    top: 0;\n    right: 0;\n    bottom: 0;\n    left: 0;\n\n    /* Display \u0026 Box Model */\n    display: inline-block;\n    overflow: hidden;\n    box-sizing: border-box;\n    width: 100px;\n    height: 100px;\n    padding: 10px;\n    border: 10px solid #333;\n    margin: 10px;\n\n    /* Other */\n    background: #000;\n    color: #fff;\n    font-family: sans-serif;\n    font-size: 16px;\n    text-align: right;\n}\n```\n\nLarger teams may prefer the simplicity and ease-of-maintenance that comes with\nalphabetical ordering.\n\n#### Exceptions and slight deviations\n\nLarge blocks of single declarations can use a slightly different, single-line\nformat. In this case, a space should be included after the opening brace and\nbefore the closing brace.\n\n```css\n.selector-1 { width: 10%; }\n.selector-2 { width: 20%; }\n.selector-3 { width: 30%; }\n```\n\nLong, comma-separated property values - such as collections of gradients or\nshadows - can be arranged across multiple lines in an effort to improve\nreadability and produce more useful diffs. There are various formats that could\nbe used; one example is shown below.\n\n```css\n.selector {\n    background-image:\n        linear-gradient(#fff, #ccc),\n        linear-gradient(#f3c, #4ec);\n    box-shadow:\n        1px 1px 1px #000,\n        2px 2px 1px 1px #ccc inset;\n}\n```\n\n### Preprocessors: additional format considerations\n\nDifferent CSS preprocessors have different features, functionality, and syntax.\nYour conventions should be extended to accommodate the particularities of any\npreprocessor in use. The following guidelines are in reference to Sass.\n\n* Limit nesting to 1 level deep. Reassess any nesting more than 2 levels deep.\n  This prevents overly-specific CSS selectors.\n* Avoid large numbers of nested rules. Break them up when readability starts to\n  be affected. Preference to avoid nesting that spreads over more than 20\n  lines.\n* Always place `@extend` statements on the first lines of a declaration\n  block.\n* Where possible, group `@include` statements at the top of a declaration\n  block, after any `@extend` statements.\n* Consider prefixing custom functions with `x-` or another namespace. This\n  helps to avoid any potential to confuse your function with a native CSS\n  function, or to clash with functions from libraries.\n\n```scss\n.selector-1 {\n    @extend .other-rule;\n    @include clearfix();\n    @include box-sizing(border-box);\n    width: x-grid-unit(1);\n    // other declarations\n}\n```\n\n\n\u003ca name=\"example\"\u003e\u003c/a\u003e\n## 5. Practical example\n\nAn example of various conventions.\n\n```css\n/* ==========================================================================\n   Grid layout\n   ========================================================================== */\n\n/**\n * Column layout with horizontal scroll.\n *\n * This creates a single row of full-height, non-wrapping columns that can\n * be browsed horizontally within their parent.\n *\n * Example HTML:\n *\n * \u003cdiv class=\"grid\"\u003e\n *     \u003cdiv class=\"cell cell-3\"\u003e\u003c/div\u003e\n *     \u003cdiv class=\"cell cell-3\"\u003e\u003c/div\u003e\n *     \u003cdiv class=\"cell cell-3\"\u003e\u003c/div\u003e\n * \u003c/div\u003e\n */\n\n/**\n * Grid container\n *\n * Must only contain `.cell` children.\n *\n * 1. Remove inter-cell whitespace\n * 2. Prevent inline-block cells wrapping\n */\n\n.grid {\n    height: 100%;\n    font-size: 0; /* 1 */\n    white-space: nowrap; /* 2 */\n}\n\n/**\n * Grid cells\n *\n * No explicit width by default. Extend with `.cell-n` classes.\n *\n * 1. Set the inter-cell spacing\n * 2. Reset white-space inherited from `.grid`\n * 3. Reset font-size inherited from `.grid`\n */\n\n.cell {\n    position: relative;\n    display: inline-block;\n    overflow: hidden;\n    box-sizing: border-box;\n    height: 100%;\n    padding: 0 10px; /* 1 */\n    border: 2px solid #333;\n    vertical-align: top;\n    white-space: normal; /* 2 */\n    font-size: 16px; /* 3 */\n}\n\n/* Cell states */\n\n.cell.is-animating {\n    background-color: #fffdec;\n}\n\n/* Cell dimensions\n   ========================================================================== */\n\n.cell-1 { width: 10%; }\n.cell-2 { width: 20%; }\n.cell-3 { width: 30%; }\n.cell-4 { width: 40%; }\n.cell-5 { width: 50%; }\n\n/* Cell modifiers\n   ========================================================================== */\n\n.cell--detail,\n.cell--important {\n    border-width: 4px;\n}\n```\n\n\n## Translations\n\n* [Bahasa Indonesia](https://github.com/necolas/idiomatic-css/tree/master/translations/id-ID)\n* [Bulgarian](https://github.com/vestimir/idiomatic-css)\n* [Česky](https://github.com/necolas/idiomatic-css/tree/master/translations/cs-CZ)\n* [Dansk](https://github.com/necolas/idiomatic-css/tree/master/translations/da-DK)\n* [Deutsch](https://github.com/necolas/idiomatic-css/tree/master/translations/de-DE)\n* [Español](https://github.com/necolas/idiomatic-css/tree/master/translations/es-ES)\n* [Français](https://github.com/necolas/idiomatic-css/tree/master/translations/fr-FR)\n* [Italiano](https://github.com/necolas/idiomatic-css/tree/master/translations/it-IT)\n* [日本語](https://github.com/necolas/idiomatic-css/tree/master/translations/ja-JP)\n* [한국어](https://github.com/necolas/idiomatic-css/tree/master/translations/ko-KR)\n* [Nederlands](https://github.com/necolas/idiomatic-css/tree/master/translations/nl-NL)\n* [Polski](https://github.com/necolas/idiomatic-css/tree/master/translations/pl-PL)\n* [Português (Brasil)](https://github.com/necolas/idiomatic-css/tree/master/translations/pt-BR)\n* [Русский](https://github.com/necolas/idiomatic-css/tree/master/translations/ru-RU)\n* [Srpski](https://github.com/necolas/idiomatic-css/tree/master/translations/sr-SR)\n* [Türkçe](https://github.com/necolas/idiomatic-css/tree/master/translations/tr-TR)\n* [正體中文](https://github.com/necolas/idiomatic-css/tree/master/translations/zh-TW)\n* [简体中文](https://github.com/necolas/idiomatic-css/tree/master/translations/zh-CN)\n\n\n\u003ca name=\"acknowledgements\"\u003e\u003c/a\u003e\n## Acknowledgements\n\nThanks to everyone who has provided translations and to all those who\ncontributed to [idiomatic.js](https://github.com/rwldrn/idiomatic.js). It was a\nsource of inspiration, quotations, and guidelines.\n\n\n\u003ca name=\"license\"\u003e\u003c/a\u003e\n## License\n\n_Principles of writing consistent, idiomatic CSS_ by Nicolas Gallagher is\nlicensed under the [Creative Commons Attribution 3.0 Unported\nLicense](http://creativecommons.org/licenses/by/3.0/). This applies to all\ndocuments and translations in this repository.\n\nBased on a work at\n[github.com/necolas/idiomatic-css](https://github.com/necolas/idiomatic-css).\n","funding_links":[],"categories":["Others","Styling","CSS","Style Guides \u0026 best practices","Uncategorized","Learning Resources","Code Style Guidelines :book:","代码风格指导"],"sub_categories":["CSS","Uncategorized","Standards / Best Practices","Editor's Draft :black_nib:"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnecolas%2Fidiomatic-css","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnecolas%2Fidiomatic-css","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnecolas%2Fidiomatic-css/lists"}