{"action":"created","issue":{"url":"https://api.github.com/repos/HugoGiraudel/sass-guidelines/issues/146","labels_url":"https://api.github.com/repos/HugoGiraudel/sass-guidelines/issues/146/labels{/name}","comments_url":"https://api.github.com/repos/HugoGiraudel/sass-guidelines/issues/146/comments","events_url":"https://api.github.com/repos/HugoGiraudel/sass-guidelines/issues/146/events","html_url":"https://github.com/HugoGiraudel/sass-guidelines/issues/146","id":57947802,"number":146,"title":"Add \"Component Structure\" section to guidelines","user":{"login":"davidkpiano","id":1093738,"avatar_url":"https://avatars.githubusercontent.com/u/1093738?v=3","gravatar_id":"","url":"https://api.github.com/users/davidkpiano","html_url":"https://github.com/davidkpiano","followers_url":"https://api.github.com/users/davidkpiano/followers","following_url":"https://api.github.com/users/davidkpiano/following{/other_user}","gists_url":"https://api.github.com/users/davidkpiano/gists{/gist_id}","starred_url":"https://api.github.com/users/davidkpiano/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/davidkpiano/subscriptions","organizations_url":"https://api.github.com/users/davidkpiano/orgs","repos_url":"https://api.github.com/users/davidkpiano/repos","events_url":"https://api.github.com/users/davidkpiano/events{/privacy}","received_events_url":"https://api.github.com/users/davidkpiano/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":2,"created_at":"2015-02-17T16:40:30Z","updated_at":"2015-02-18T13:28:39Z","closed_at":null,"body":"One thing that would be tremendously useful in the guidelines is how to actually organize the **content** of a component file, e.g. `components/_buttons.scss`. I've tended towards this (opinionated) structure:\r\n\r\n- **Variables** - component-specific variables (whether singular variables or maps) to prevent magic numbers\r\n- **Functions** - any component-specific functions, if applicable\r\n- **Mixins** - component-specific, if applicable for dynamically generating variations of the component (not necessary in many cases, if few variations exist)\r\n- **Structures** - the CSS component layout/structure, excluding any non-layout rules, such as color\r\n- **Relationships** - any component-specific CSS with regard to relationships (via combinators) with other components\r\n- **Themes** - thematic CSS for non-layout component styling, such as background, colors, shadows, etc.\r\n- **Exports** - the manifested CSS classes, if they are to be exposed\r\n\r\nHere is how a component-specific file would look with this structure, with a `button` component as an example:\r\n\r\n```scss\r\n// Variables\r\n$button-color: blue;\r\n$button-width: 5rem;\r\n// ... etc.\r\n\r\n// Functions\r\n// ... not applicable for buttons. Can remove this section.\r\n\r\n// Mixins\r\n@mixin button-theme($color: $button-color) {\r\n  background-color: $color;\r\n  // ... etc.\r\n}\r\n\r\n// Structure\r\n%button {\r\n  display: block;\r\n  width: $button-width;\r\n  // ... etc.\r\n}\r\n\r\n// Relationships\r\n%button {\r\n  %buttonGroup > & {\r\n    display: inline-block;\r\n    // ... etc.\r\n  }\r\n}\r\n\r\n// Themes\r\n%button {\r\n  @include button-theme($color: $button-color);\r\n\r\n  &-secondary {\r\n    @include button-theme($color: gray);\r\n  }\r\n}\r\n\r\n// Exports\r\n.my-button {\r\n  @extend %button;\r\n\r\n  &.secondary {\r\n    @extend %button-secondary;\r\n  }\r\n}\r\n```\r\n\r\nIf you don't want to use placeholders in the guidelines, these can easily be subbed out for classes. I use placeholders above for a couple reasons:\r\n- Resilience to nomenclature change. If class names change, they only need to be changed in one place - in the **Exports** section.\r\n- Ability to \"remove\" from output CSS without side effects. If `%foo` component extends `%bar` component, but I decide to remove the `.bar` class, neither `%foo` nor `.foo` will be affected.\r\n\r\nOther considerations:\r\n- Structure, relationship, and themes, still in that order, but within the same parent placeholder instead of having to be nested 3 different times? I can go either way.\r\n- Should we add **States** to this organization? In the above structure, that would include `%button-disabled`, `%button-focus`, etc.\r\n\r\nLet me know what you think! In the past, I've had each of these sections in different files, but I'm moving towards having them in a single file, with an enforced order and organization.\r\n"},"comment":{"url":"https://api.github.com/repos/HugoGiraudel/sass-guidelines/issues/comments/74863317","html_url":"https://github.com/HugoGiraudel/sass-guidelines/issues/146#issuecomment-74863317","issue_url":"https://api.github.com/repos/HugoGiraudel/sass-guidelines/issues/146","id":74863317,"user":{"login":"davidkpiano","id":1093738,"avatar_url":"https://avatars.githubusercontent.com/u/1093738?v=3","gravatar_id":"","url":"https://api.github.com/users/davidkpiano","html_url":"https://github.com/davidkpiano","followers_url":"https://api.github.com/users/davidkpiano/followers","following_url":"https://api.github.com/users/davidkpiano/following{/other_user}","gists_url":"https://api.github.com/users/davidkpiano/gists{/gist_id}","starred_url":"https://api.github.com/users/davidkpiano/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/davidkpiano/subscriptions","organizations_url":"https://api.github.com/users/davidkpiano/orgs","repos_url":"https://api.github.com/users/davidkpiano/repos","events_url":"https://api.github.com/users/davidkpiano/events{/privacy}","received_events_url":"https://api.github.com/users/davidkpiano/received_events","type":"User","site_admin":false},"created_at":"2015-02-18T13:28:39Z","updated_at":"2015-02-18T13:28:39Z","body":"Sounds good!"}}