1 | ## Setup
|
2 |
|
3 | ### Built-In Tools
|
4 |
|
5 | From the Fomantic directory you can setup gulp to build Fomantic by running.
|
6 |
|
7 | ```bash
|
8 | npm install
|
9 | ```
|
10 |
|
11 | Fomantic will automatically configure itself using a `post-install` script built into the package.
|
12 |
|
13 | After set-up can use gulp to build your project's css:
|
14 |
|
15 | ```bash
|
16 | # Watch files
|
17 | gulp watch
|
18 |
|
19 | # Build all files
|
20 | gulp build
|
21 | ```
|
22 |
|
23 | Visit the [Getting Started Guide](http://learnsemantic.com/guide/expert.html) for more details on set-up
|
24 |
|
25 | ### Custom Pipelines
|
26 |
|
27 | #### Importing Gulp Tasks
|
28 |
|
29 | Each gulp task can be imported into your own Gulpfile using `require`
|
30 |
|
31 | ```javascript
|
32 | const watch = require('path/to/semantic/tasks/watch');
|
33 |
|
34 | gulp.task('watch ui', 'Watch Fomantic-UI', watch);
|
35 | ```
|
36 |
|
37 | #### Importing LESS
|
38 |
|
39 | > LESS files do not contain vendor prefixes. If you are to use these files directly you must add them during your build step.
|
40 |
|
41 | Before using source files you will need to create a `theme.config` by renaming `theme.config.example`, and a site folder by renaming `_site/` to `site/`
|
42 |
|
43 | You can then import Fomantic from your own LESS files:
|
44 |
|
45 | ```less
|
46 | /* Import all components */
|
47 | @import 'src/semantic';
|
48 | ```
|
49 |
|
50 | To import individual components you will have to create a scope for each import using `& {}`
|
51 |
|
52 | ```less
|
53 | /* Import a specific component */
|
54 | & { @import 'src/definitions/elements/button'; }
|
55 | ```
|
56 |
|
57 | ### Config Files
|
58 |
|
59 | These files are generated automatically using install scripts, but must be manually renamed if you are using installing manually.
|
60 |
|
61 | filename | usage | Initial Name
|
62 | --- | --- | ---
|
63 | **theme.config** | config file that stores each element's current theme for LESS | theme.config.example
|
64 | **site/** | folder storing all your site's variables and css overrides for each UI component | _site/
|
65 | **semantic.json** | stores folder paths for build tools and current installed version for updates. Only necessary when using build tools | semantic.json.example
|
66 |
|
67 | ### Workflow
|
68 |
|
69 | You will only need to use Fomantic's build tools while refining your UI. When designing pages, you can rely on the compiled css packages in `dist/`.
|
70 |
|
71 | When creating your UI you can try <a href="http://www.learnsemantic.com/themes/creating.html">downloading different themes</a>, adjusting your <a href="http://www.learnsemantic.com/developing/customizing.html#setting-global-variables">site-wide settings</a> (font-family, colors, etc) and tweaking components in your site's <a href="http://www.learnsemantic.com/developing/customizing.html#designing-for-the-long-now">component overrides</a>.
|
72 |
|
73 | Files in the `examples/` folder of your project can be useful for testing out changes in your UI. For example, you might run `gulp watch` download a new theme to `src/site/themes/` then adjust your `theme.config` file with the name of the new theme and refresh `examples/kitchensink.html` to inspect changes in the theme.
|
74 |
|
75 | ## Theming
|
76 |
|
77 | ### Concepts
|
78 |
|
79 | #### Inheritance
|
80 |
|
81 | There are three levels of inheritance in Fomantic
|
82 | * Default theme - Fomantic-UI's neutral default theme
|
83 | * Packaged theme - A specified packaged theme, like "amazon", or "material"
|
84 | * Site theme - A theme specific to your site
|
85 |
|
86 | #### Folder Structure
|
87 |
|
88 | * `definitions/` contains the `css` and `javascript` definitions for each component
|
89 | * `themes/` contains *pre-packaged themes* including Fomantic's default theme
|
90 | * `site/` contains your current site's theme
|
91 |
|
92 | View the [Theming Guide](http://learnsemantic.com/themes/overview.html) for a more in-depth look
|
93 |
|
94 | ## Customizing
|
95 |
|
96 | #### Basic Customization
|
97 |
|
98 | The best way to start customizing is to specify overriding variables in your site's `site.variables` file.
|
99 |
|
100 | This is a blank stub file that lets you specify variables that overriding variables.
|
101 |
|
102 | Some important values to customize:
|
103 | * Base font size
|
104 | * Named color hex codes
|
105 | * Header/Page Font-families
|
106 | * Primary and secondary colors
|
107 | * Grid column count
|
108 |
|
109 | To find out what variables are available to modify, you can inspect the variables in the default theme in `themes/default/`
|
110 |
|
111 | #### Advanced Configuration
|
112 |
|
113 | Each component has its own variable file, which can be used to modify any of the underlying variables for that component.
|
114 |
|
115 | For example `/site/elements/button.variables`.
|
116 |
|
117 | You may also specify your own custom LESS in `site/elements/button.overrides`. This file will have access to all underlying variables available for that component.
|
118 |
|
119 | #### Using Pre-Packaged Themes
|
120 |
|
121 | You can modify `theme.config` to use any prepackaged theme available in `src/themes/`.
|
122 |
|
123 | For example you can modify `theme.config` to use a `github` button theme by changing
|
124 |
|
125 | ```less
|
126 | @button: 'github';
|
127 | ```
|
128 |
|
129 | View the [Customization Guide](http://learnsemantic.com/developing/customizing.html) to learn more
|