├── LICENSE ├── README.md ├── generator ├── index.js └── template │ ├── config │ └── storybook │ │ ├── addons.js │ │ ├── config.js │ │ ├── style.scss │ │ └── webpack.config.js │ ├── private │ └── jest │ │ └── svgMock.js │ └── src │ ├── components │ ├── atoms │ │ └── _gitkeep │ ├── molecules │ │ └── _gitkeep │ ├── organisms │ │ └── _gitkeep │ ├── pages │ │ └── _gitkeep │ └── templates │ │ └── _gitkeep │ ├── router.js │ ├── store.js │ └── storeModules │ └── _gitkeep ├── index.js ├── package.json ├── prompts.js └── vue-atomic-design.png /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018 Milad Alizadeh 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Vue Atomic Design 2 | 3 | ![Vue Atomic Design](https://raw.githubusercontent.com/milad-alizadeh/vue-cli-plugin-atomic-design/master/vue-atomic-design.png) 4 | 5 | Vue Atomic Design is an opinionated Vue CLI 3 plugin for using [Atomic Design](http://bradfrost.com/blog/post/atomic-web-design/) methodology with Vue.js. 6 | 7 | Related projects: 8 | 9 | * [Vue Atomic Design Components](https://github.com/milad-alizadeh/vue-cli-plugin-atomic-design-components) - A library of Vue components based on Atomic Design 10 | 11 | * [Vue SCSS Base](https://github.com/milad-alizadeh/vue-cli-plugin-scss-base) - A starter SCSS base for Vue projects 12 | 13 | ## How to install 14 | 15 | You first need to install Vue Cli 3 16 | 17 | ``` 18 | npm install -g @vue/cli 19 | # OR 20 | yarn global add @vue/cli 21 | ``` 22 | 23 | Then you can add the plugin by typing the following command 24 | 25 | ``` 26 | vue add atomic-design 27 | ``` 28 | 29 | ## Storybook 30 | Vue Atomic Design uses [Storybook](https://storybook.js.org/) as its design system tool. Originally created for React, Storybook is a tool for creating UI Components in isolation. The advantage of using Storybook is that we can create our style guide and our project at the very same time without maintaining both which is great for both small and large scale applications. 31 | Once you install the plugin the storybook will be configured and you can use it by running: 32 | 33 | ```yarn run serve:storybook``` 34 | 35 | or to generate a static style guide: 36 | 37 | ```yarn run build:storybook``` 38 | 39 | 40 | ## Structure 41 | Atomic design has a very clean approach in grouping components through composition which is a a great combination with Vue.js 42 | 43 | The summary of Atomic Design structure is as Follows. 44 | 45 | ### Atoms 46 | An atom is a native html tag. A Vue components that renders only one tag such as `div`, `p` or any other. 47 | 48 | ``` 49 | // atoms/VButton.vue 50 | 51 | 56 | 57 | ``` 58 | or 59 | 60 | ``` 61 | // atoms/VInput.vue 62 | 63 | 82 | ``` 83 | 84 | ### Organisms 85 | 86 | An organism is a combination of atoms, molecules and other organisms 87 | 88 | ``` 89 | // organsims/Header.vue 90 | 91 | 98 | ``` 99 | 100 | ### Templates 101 | A combination of organisms, molecules and atoms to form a complete page. Templates only have dummy placeholder content. 102 | 103 | ``` 104 | // templates/VPageTemplate.vue 105 | 106 | 113 | 114 | ``` 115 | 116 | ### Pages 117 | 118 | Pages are essentially instances of templates with real representative content. This is generally the point where Vuex connects to our templates. The benefit of this approach is the separation of data and UI and it enables you to create your UI regardless of where your data actually comes from. This also makes the testing much easier. 119 | 120 | ``` 121 | // pages/VPostPage.vue 122 | 123 | 130 | 131 | 144 | 145 | ``` 146 | 147 | ### File names and CSS class names 148 | It is highly recommended that all the filenames be prefixed with a base such as `App` or `V`. This prevents conflicts with existing and future HTML elements, since all HTML elements are a single word. 149 | It is also recommended using namespaced class names and [BEM](https://en.bem.info/methodology/) for your CSS. The prefred format is `'componentTypeInitial-prefix-componentName'`. For example `Atom/VButton` class name will `a-v-button`. This ensures any conflix with imported CSS frameworks and makes debugging easier. 150 | 151 | However you can scope your stying using other methods such as `scoped` attribute, CSS modules or any other library/convention 152 | 153 | ### Folder Structure 154 | 155 | In order to make organisation simpler, each component has a folder with its name which has 3 files in it. `index.vue`, `index.stories.js` and `index.test.js`. With this structure the unit tests, stories and the component will be in the same place without clutter. For example: 156 | 157 | ``` 158 | - components 159 | - atoms 160 | - VButton 161 | - index.vue 162 | - index.stories.js 163 | - index.test.js 164 | - VInput 165 | - index.vue 166 | - index.stories.js 167 | - index.test.js 168 | - molecules 169 | - VSearchInput 170 | - index.vue 171 | - index.stories.js 172 | - index.test.js 173 | ``` 174 | 175 | With following this structure all of the stories will be created on runtime. 176 | 177 | #### Storybook 178 | Can you categories storybook stories by naming the story module to '{Category} - {Component Name}'. For example: 179 | 180 | ``` 181 | storiesOf('Atom - VButton', module) 182 | .add('default', () => ({ 183 | components: { VButton }, 184 | template: '' 185 | })); 186 | 187 | ``` 188 | 189 | #### Unit Tests 190 | Unit testing is an important part of any web project however it might require some setup and testing. Vue Atomic Design uses Jest as its testing tool. An example of a unit test for the `VButton` components would be: 191 | 192 | ``` 193 | import { mount } from '@vue/test-utils' 194 | import VButton from '.' 195 | 196 | describe('Atom - VButton', () => 197 | test('Tag should be if href prop is set', () => { 198 | const wrapper = mount(VButton, { 199 | propsData: { href: 'http://google.com' } 200 | }) 201 | 202 | expect(wrapper.contains('a')).toBe(true) 203 | expect(wrapper.attributes().href).toBe('http://google.com') 204 | }) 205 | }) 206 | 207 | ``` 208 | 209 | #### Vuex 210 | 211 | This plugin takes a [modular](https://vuex.vuejs.org/guide/modules.html) approach to organising Vuex store. Each feature of your app is seperated into a module which include its own state, mutations, actions and getters. For example: 212 | 213 | ``` 214 | - storeModules 215 | - posts 216 | - index.js 217 | - users 218 | - index.js 219 | ``` 220 | 221 | For example storeModules/users/index.js will contain the following: 222 | 223 | ``` 224 | const state = { 225 | userList: [] 226 | } 227 | 228 | const mutations = { 229 | setUsers (state, payload) { 230 | state.userList = payload 231 | } 232 | } 233 | 234 | const actions = { 235 | async getUsers ({ commit }, username) { 236 | let response = await fetch(`//api.github.com/users`) 237 | let users = await response.json() 238 | commit('setUsers', users) 239 | } 240 | } 241 | 242 | export default { 243 | state, 244 | mutations, 245 | actions 246 | } 247 | 248 | ``` 249 | 250 | you can then reference this module in your app like: 251 | 252 | ``` 253 | 258 | 259 |